diff --git a/CHANGELOG.md b/CHANGELOG.md index a76665942..e8e4b30cd 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -8,13 +8,26 @@ What a version number promises before 1.0 is described in [docs/VERSIONING.md](d ## [Unreleased] +Members-only content in public repositories, Environments and the secret scan. People using older Forge builds see fewer things until they update: they leave members-only items out, and they don't count a members-only review's approval, so they may refuse a merge an up-to-date build allows. **Update to see and count members-only reviews.** [Who can read what](docs/security/audiences.md) explains the audiences, what stays public and what can still leak. + ### Added -- **Members-only discussion from `dg`** in public repositories with members-only content turned on: `--members` on `dg issue create`, `dg issue comment`, `dg pr comment` and `dg pr review`. Members read it in `dg issue view/list` and `dg pr view/list`; everyone else sees "#3 · members-only issue by @alice · open" and "3 members-only comments hidden". Every item in `--json` carries `"audience"` and `"readable"`. +- **Members-only content in public repositories.** A maintainer turns it on once with `dg repo members enable` (it shows the cost first: about 0.004 DASH for 5 members), and `dg repo members status` shows who has the key. Members can then post issues, comments and reviews only members can read: maintainers, writers, triage members and readers, including members added later. Removed members keep what they could already read. CI runners are not members. Everyone can still see that something was posted, by whom, when and how large, and a review's verdict. +- **Members-only discussion from `dg`** in public repositories with members-only content turned on: `--members` on `dg issue create`, `dg issue comment`, `dg pr comment` and `dg pr review`. Members read it in `dg issue view/list` and `dg pr view/list`; everyone else sees "#3 · members-only issue by @alice · open" and "3 members-only comments hidden". Every item in `--json` carries `"audience"` and `"readable"`. A members-only text longer than its field is stored encrypted (by maintainers and writers), and a members-only pending review is kept encrypted on disk. +- **Readers on public repositories.** `dg collab add --role reader` works on public repositories: a reader follows the members-only discussion without pushing or merging. +- **Membership changes follow the members key.** On a repository with members-only content, `dg collab add` shares the key with the new member and `dg collab remove` changes it, as on a private repository. `dg repo keys status`, `repair` and `rotate` work there too. A member added by an older build sees E311 until a maintainer's repair shares the key. +- **A members-only review's approval counts for everyone**, member or not, so everyone sees the same merge button. +- **The web app** reads members-only issues, comments and reviews for members after one unlock per tab, keeps a reply in a members-only conversation members-only, offers the reader role on public repositories, and shares or changes the key when members are added or removed. +- **Members-only content in the web app.** A maintainer turns it on with **Turn on members-only content**, which shows the cost first. Every composer has an audience chip (Public or Members). Everyone else sees members-only rows, placeholders and a "#N · members-only" page, never the text. Members can check the public's view with **View as public**. The web asks before a public post that quotes members-only text, and keeps no members-only draft on disk. A removed member still reads what was written while they were a member. +- **Settings → Environments** in the web app shows a repository's environments to the people who can read them, with values hidden until you show one; others see only how many there are. Changes are made with `dg env`. +- **Environments** (`dg env`): configuration and secrets kept outside git, encrypted for a repository's **Maintainers** (the default for `production`, `prod*`, `staging` and `release*`) or its **Members**, changed by maintainers only, injected with `dg env run` or written to a git-ignored file with `dg env export -o .env`. Two changes at once fail closed (E608) until a maintainer keeps one. `dg collab remove` lists the values the removed member could read. See [Environments](docs/guides/environments.md). +- **Secrets in a public push.** `git push` to a public repository checks every file it publishes for the first time. It refuses a new `.env` file, a PEM private key, an AWS key pair or a GitHub or GitLab token with a valid checksum (E807), and warns about `.envrc` files, random-looking values and keys in test folders. `-o allow-secret=` or `.forge/secret-scan-allow` lets a checked finding through. See [Secrets in a push](docs/guides/quick-start.md#secrets-in-a-push). +- **Wallet sign-in keeps your encryption key.** The web app stores the encryption key the Dash Wallet registers in the browser's vault, every one of them across approvals, so private repositories and members-only content open after one unlock per tab. When the identity's key came from somewhere else, it says "Your encryption key is held elsewhere. Import it under Settings → Private repos." ### Changed - `dg repo view` counts git packs only: `packCount` and `packBytes` (and the `packs:` line) no longer include browse indexes, history indexes, release-asset lists or long bodies. `dg storage status` still lists every artifact. +- Notifications and `forge-relay` webhooks never carry members-only text: they say that something happened, by whom and where. An encrypted comment or review from someone who is not a member is not shown and notifies nobody. ## [0.1.0] - 2026-10-04 diff --git a/crates/dg/src/audience.rs b/crates/dg/src/audience.rs index d0c409a68..dff210e2c 100644 --- a/crates/dg/src/audience.rs +++ b/crates/dg/src/audience.rs @@ -96,7 +96,7 @@ pub fn why_hint(repo: &RepoRef, why: Unopened) -> Option { "you're a member of {r}, but the key stored on this computer holds no encryption key (`dg auth status`)" )), Unopened::NoKeyShared => Some(format!( - "you're a member of {r}, but no key has been shared with you yet; a maintainer's client will fix this the next time they open the repo" + "you're a member of {r}, but no key has been shared with you yet. Ask a maintainer to share it: Repair on the repo page, or `dg repo keys repair {r}`" )), Unopened::NotReadable => Some(format!( "written for a key you do not hold (after you were removed, or late); `dg repo keys status {r}` lists your keys" diff --git a/crates/dg/src/collab.rs b/crates/dg/src/collab.rs index 3cde75936..bc4939696 100644 --- a/crates/dg/src/collab.rs +++ b/crates/dg/src/collab.rs @@ -215,7 +215,7 @@ async fn add(ctx: &Ctx, repo: &str, member: &str, role: RoleArg, wait: Option Error { ), ) .cause("members-only content is encrypted to each member's key, and no maintainer has shared that key with you yet") - .fix(fix_repair(repo)) - .note("a maintainer's client fixes this the next time they open the repo") + .fix(format!( + "ask a maintainer to share it: Repair on the repo page, or `dg repo keys repair {}`", + repo.display() + )) .into() } @@ -259,7 +261,7 @@ pub fn no_encryption_key(member: &str, action: &str) -> Error { format!("{action}: {member} has no encryption key"), ) .cause("private repositories encrypt their content to each member's identity ENCRYPTION key, and this identity has no enabled one") - .fix(format!("they add one themselves: `{FIX_ADD_ENCRYPTION_KEY}`, or Settings → Keys → Enable private repos in the web app")) + .fix(format!("they add one themselves: `{FIX_ADD_ENCRYPTION_KEY}`, or Settings → Private repos → Enable private repos in the web app")) .into() } diff --git a/docs/contracts/forge-v2.md b/docs/contracts/forge-v2.md index 0fe44132d..0422dd150 100644 --- a/docs/contracts/forge-v2.md +++ b/docs/contracts/forge-v2.md @@ -63,7 +63,7 @@ Two RC1 conventions recur in the tables: | `refUpdate` | M or W1, each operand with `where {"vis": "vis"}` (the writer operand also `{"role": "r"}`, `r` 1) | no | **no** | `(repoId, refNameHash, $createdAt)` ref state, `(repoId, $createdAt)` reflog, `(repoId, $ownerId, $createdAt)` pusher; `refName` follows git's ref-name grammar (R-01: `$defs.refName`, `refs/` prefix, `@{` refused) and `noLock` refuses a trailing `.lock`; `oidWidth` (R-10): `newOid` 20 or 32 bytes, `prevOid` absent, 20 or 32; `noPlain` with `vis` and `hasName`: a private ref update is sealed (§5) | | `protectedRefUpdate` | M, with `where {"vis": "vis"}` | no | **no** | same indexes and rules | | `config` | M, with `where {"vis": "vis"}` | no | **no** | append-only, newest wins; `defaultBranch` uses `$defs.branch`; `protectedPatterns` ≤ 8, `uniqueItems` (INV-11); `backend.uris` typed string array; `noPlain` with `vis` (§5); `encV2`: an `enc` is at least 61 bytes (the key-committing layout) | -| `packManifest` | M or W1 (`r` 1) | no | **no** | unique `(repoId, $ownerId, packHash)`; `(repoId, packHash)` lookup; `(repoId, $createdAt)` rangeCountable (pack count); `(repoId, kind, $createdAt)`; `bytes (repoId, storage, kind)` summable on `sizeBytes` (O-05). `packHash` is an identifier (`$defs.hid`, R-09). `kind` (an open integer, 0..255; only kind 3's `tips` shape is a rule): 0 git pack, 1 `objectLocator`, 2 `flatIndex`, 3 history column index, **4 `releaseAssets`** (a release's full asset list, named by `release.assetManifest`; `docs/design/release-asset-manifest.md`), 5 history version lists (the companion of kind 3 with the same `tips`, which the contract checks on kind 3 only; the format is the artifact header's; `docs/design/history-index.md`), **6 long body** (the full text of an issue, PR, comment, review or release notes longer than its field, named by the field's trailer; a client convention, §6.3). Rules: `platformChunks` (R-09: with `storage = 0`, the uploader's chunks for the pack number exactly `chunkCount` and their `seq` sum is `n(n−1)/2`, which with the unique `seq` index means `0..n−1` are all present, so a manifest is written after its chunks); `storageShape` (`storage = 0`: `sizeBytes ≤ chunkCount × 14,700`; `storage = 1`: `chunkCount = 0`); `kindShape` (R-11: `supersedes` a multiple of 32 bytes; a kind-3 manifest's `tips` are 20, 32, 40 or 64 bytes); `sizeNonNeg` (`sizeBytes` is a plain integer, as a summable property must be, bounded to 0..1 TiB by the rule) | +| `packManifest` | M or W1 (`r` 1) | no | **no** | unique `(repoId, $ownerId, packHash)`; `(repoId, packHash)` lookup; `(repoId, $createdAt)` rangeCountable (pack count); `(repoId, kind, $createdAt)`; `bytes (repoId, storage, kind)` summable on `sizeBytes` (O-05). `packHash` is an identifier (`$defs.hid`, R-09). `kind` (an open integer, 0..255; only kind 3's `tips` shape is a rule): 0 git pack, 1 `objectLocator`, 2 `flatIndex`, 3 history column index, **4 `releaseAssets`** (a release's full asset list, named by `release.assetManifest`; `docs/design/release-asset-manifest.md`), 5 history version lists (the companion of kind 3 with the same `tips`, which the contract checks on kind 3 only; the format is the artifact header's; `docs/design/history-index.md`), **6 long body** (the full text of an issue, PR, comment, review or release notes longer than its field, named by the field's trailer; a client convention, §6.3), and the client conventions of §5.1: **7** reveal bundle (reserved), **8 environment snapshot**, **9** environment registry (reserved), **10** branch grant (reserved), **64 + k** the members-only form of kind k in a public repo (64–69 reserved), **70 members-only long body**. Rules: `platformChunks` (R-09: with `storage = 0`, the uploader's chunks for the pack number exactly `chunkCount` and their `seq` sum is `n(n−1)/2`, which with the unique `seq` index means `0..n−1` are all present, so a manifest is written after its chunks); `storageShape` (`storage = 0`: `sizeBytes ≤ chunkCount × 14,700`; `storage = 1`: `chunkCount = 0`); `kindShape` (R-11: `supersedes` a multiple of 32 bytes; a kind-3 manifest's `tips` are 20, 32, 40 or 64 bytes); `sizeNonNeg` (`sizeBytes` is a plain integer, as a summable property must be, bounded to 0..1 TiB by the rule) | | `chunk` | M or W1 (`r` 1) | no | **no** | unique `(repoId, $ownerId, packHash, seq)`; `perPack (repoId, $ownerId, packHash)` averageable on `seq` (the count and sum `platformChunks` reads); `documentsCountable` (the chunk total, a ceiling for the fee estimator; D-3, kept only if its count-tree cost measures under ~5 % of a chunk write) | | `release` | **M**, with `where {"vis": "vis"}` | no | **no** (O-04) | newest per `(repoId, tagName)` wins; maintainer-only because a release names artifacts users install; `tagName` follows the ref grammar (R-01); optional `enc`/`epoch` for a private repo, with `tagName` the keyed hash of the tag; optional `assetManifest` (h32: the `packHash` of a kind-4 `packManifest` holding the full asset list when `assets` does not fit) and `imported {author, createdAt, url}` (a mirrored release). **Ledger (O-04):** required `delta` −1..1: +1 publish, 0 edit or yank (and every sealed document), −1 unpublish; `perTag (repoId, tagName)` summable and rangeSummable (a proved release count); `oneLive`: a sealed document has `delta = 0`, otherwise the tag's sum after the write is `min(delta + 1, 1)`, so a publish needs the tag not live and an edit, yank or unpublish needs it live. Clients publish an asset only under a name a download saves as itself: one plain file name, not a path, dotfile, leading dash or Windows device name, at most 255 bytes, and no two names of a release equal without case (vectors `asset_file_name__*`) | | `label` | M or W2 (`r` 1..2) | no | yes | newest per `(repoId, name)` wins; `name` has no leading or trailing whitespace and no control characters (CL-8; no per-repo cap); optional `enc`/`epoch`, `name` then the keyed hash of the name and `noPlain` refusing `color`/`description`. No `vis`: label definitions are plaintext in private repos by design (§5) | @@ -306,7 +306,7 @@ A private repo is a `repo` with `visibility: "private"`; `visibility` is immutab - Unique `(repoId, memberId, epoch, $ownerId)`; gated to maintainers (forge-core `maintainer`, across contracts); immutable and non-deletable. `$ownerId` is in the key so one maintainer cannot claim a member's slot for an epoch before another. - **Reader rule** (`docs/security/private-repos.md` §5.4, which is normative and wins over this summary). A member accepts a wrapped key for `(repo, epoch)` only if its writer is a **current** maintainer (a removed maintainer's wraps and configs are withdrawn with their membership), the epoch exists (it has an anchor: the first config for it, by `($createdAtBlockHeight, $id)`, written by a current maintainer), the unwrapped plaintext `0x01 ‖ KCV_e ‖ K_e` has a matching 14-byte key-check value (error detection only), and `COMMIT_e` derived from the key equals the commitment the anchor's `enc` v0x02 carries. A key that fails the last check raises a `KeyMismatch` alert naming the wrap's author; the reader never looks for another config the key opens. Older epochs are reached only through the anchors' `prevEpochKey` chain. - A wrap that lands before a concurrent removal is still accepted by consensus and needs the repair of private-repos.md §5.6. -- **Readers** (ROLES, §2.1): a `writer` document with `role` 3 is a member for the key like any other, so it is wrapped every epoch and removing it rotates the epoch; it can write nothing role-gated. A reader can leak the key, as on any read role. +- **Readers** (ROLES, §2.1): a `writer` document with `role` 3 is a member for the key like any other, so it is wrapped every epoch and removing it rotates the epoch; it can write nothing role-gated. A reader can leak the key, as on any read role. Consensus admits a reader on a public repo too (`writer` has no `vis` clause); there it holds the members key of §5.1. - **Rotation.** On removing a member, a maintainer posts epoch `n+1` wraps for the remaining members (self first), then the anchor `config` for `n+1` (carrying `prevEpoch = n` and `K_n`), and writes under `n+1` only after a proof-verified read shows its anchor is first. Future content uses the new key. Past content stays readable to past members, and the product says so plainly. Content written under a superseded epoch more than 240 blocks after the next epoch's key was first stated on chain (the first config carrying its anchor's commitment, so a re-anchor does not move it) by a non-member is hidden (the late-content rule, private-repos.md §8.2). - **Encrypted fields.** `issue`, `patch`, `comment` and `review` take `enc` plus `epoch`, and leave the plaintext `title`/`body` (and an inline comment's `path`) empty. `refUpdate`, `protectedRefUpdate`, `config` and `release` take the same `enc`/`epoch` pair. `enc` is `0x01 ‖ nonce ‖ AES-256-GCM(K_doc,e, TLV plaintext, AD) ‖ tag` under an HKDF-SHA256 subkey of the epoch key, with the associated data binding the repo, `$ownerId`, the epoch, the type and the document's plaintext identity; `config` always uses the key-committing `0x02 ‖ COMMIT_e ‖ …` layout (`encV2` refuses a shorter `enc`). Layouts, TLV tags and AD are in `docs/security/private-repos.md` §4. - A private ref update puts `refName` inside `enc` and sets `refNameHash = HMAC-SHA256(K_ref,e, refName)` under the epoch's ref subkey, so ref names cannot be recovered by dictionary and differ across epochs. `refName` is optional for this reason. A reader recomputes the hash from the decrypted name and treats a mismatch as malformed. @@ -325,6 +325,29 @@ A private repo is a `repo` with `visibility: "private"`; `visibility` is immutab The AEAD layouts, key derivation, anchors, rotation and conformance vectors are specified in `docs/security/private-repos.md` (reviewed; normative where it differs from this section). The cryptographic core is `forge-core::private` and `forge-web/lib/private`, held in byte-for-byte parity by the `private_*` vectors. +### 5.1 Members-only content in a public repo (client conventions, no contract change) + +A **public** repo may hold members-only issues, comments and reviews beside its public content (`docs/security/private-repos.md` §17 is normative; `docs/security/audiences.md` is the user-facing account). Nothing below adds a property, type, index or rule to the live contracts; every row was admitted live on devnet sakura (mixed-visibility spikes S1, S6). + +- **The members key** is the private-repo epoch chain of §5 in a public repo: `repoKey` wraps to every member (owner, maintainers, writers, triage members and **readers**), and an anchor `config` with `enc` v0x02, `vis: "public"` and no settings (consensus refuses `vis: "private"` on a public repo, 40127). A wrap to a non-member or to a runner-only identity is refused (40120): a `runner` document is not a membership, so CI runners never hold the key. Rotation on removal, burned epochs, repairs and the late-content rule run as in §5. Clients key every membership change on "this repo has a members key", never on visibility alone. +- **Readers on a public repo.** A `writer` document with `role` 3 is admitted (no `vis` clause). A reader may post issues, comments and reviews with `asMember`, like anyone, and may not push, write events, labels, milestones, refs or pack manifests (40127). +- **Members-only documents** are ordinary `issue`, `comment` and `review` documents with `vis: "public"`, `enc` v0x03 (`docs/security/private-repos.md` §4.1: per-object key, key commitment, padding to 64 bytes) and `epoch`, with their plaintext content fields absent (`noPlain`). Every member's sealed write carries `asMember`; consensus refuses `asMember` from a non-member (40120). `enc` v0x04 (specific people, `epoch` 0) is admitted in public and private repos and reserved for a later phase. An event value on a members-only target is sealed like a private repo's. +- **What stays plaintext**, by consensus: existence, `$ownerId`, times, `enc` length, numbers (members-only issues use the shared dense sequence), transitions, a review's `verdict` and `commitOid`, an inline comment's `line`, `side`, `startLine`, `commitOid` and `reviewId`, `replyTo`, event `refId`s (an assignee), label and milestone definitions. +- **Approvals.** A members-only review's plaintext `verdict` counts for every reader when it carries `asMember` (`memberVerdict` already requires `asMember` for verdicts 1 and 2), whether or not the reader opens the body (vectors `approval_count__*`). Older clients drop sealed reviews and undercount, so they refuse a merge a current client allows (E804), never the reverse. +- **Pack manifest kinds** (`kind` is open; only kind 3 is shaped; readers skip unknown kinds): + + | Kind | Use | + |---|---| + | 7 | reveal bundle (making members-only documents public): reserved | + | 8 | **environment snapshot**: one environment's canonical JSON, DFPK `0x01` under the members key (audience Members) or DFPK `0x02` to the current maintainers (audience Maintainers); `supersedes` names earlier snapshots. Written by maintainers only by client rule: consensus admits a manifest from any role-1 writer, and readers count a snapshot only from a current maintainer | + | 9 | environment registry: reserved | + | 10 | branch grant: reserved | + | 64–69 | the members-only form of kinds 0–5 (64 + k): reserved | + | 70 | **members-only long body** (64 + 6): a members-only text longer than its field, DFPK `0x01` under the members key at the write epoch; a members-only field's trailer resolves only to kind 70, a public one only to kind 6 | + + Like every `packManifest`, these need a maintainer or a role-1 writer: a triage member, a reader or a non-member cannot store a members-only long body, so their members-only text stays within its field. + + ## 6. What consensus enforces and what stays a client rule | Concern | Enforced by | @@ -445,6 +468,7 @@ answered by the countable `perRepo (repoId)` index on both types. On create the | Milestones: newest definition per title, with open / closed counts | `fold_milestones_v2` | `milestones__*` | | Trending: the window a ranked read covers, and the ranking recomputed from the beats (§4 of the parity spec) | `trending_window`, `trending_recount` | `trending__*` | | Plaintext xor `enc` (§5) | `is_well_formed` | `well_formed__*` | +| Members-only content in a public repo (§5.1): the content and git-plane predicates, an edit keeps its audience, a members-only verdict counts, the settings-free anchor | `content_well_formed`, `git_plane_well_formed`, `edit_keeps_audience`, `counted_reviews` (`rules::v2`) | `content_well_formed__*`, `git_plane_well_formed__*`, `mixed_edit__*`, `approval_count__*`, `mixed_anchor__*`, `mixed_doc_seal__*`, `mixed_doc_open__*` | | Repository names | `is_valid_repo_name`, `normalize_repo_name` | `repo_name__*` | | Long bodies (§6.3): reading a field's trailer, checking a fetched full text, the writer's prefix cut | `rules::long_body::{parse, open_public, open_text, needs_artifact, stored_text, fit_prefix}` (TS `parseLongBody`, `openPublicLongBody`, `openLongBodyText`, `needsLongBodyArtifact`, `longBodyStoredText`, `fitPrefix`) | `long_body__*` | | Private content: key derivation, ref-name hashes, `enc` seal/open with the ref-name hash check and the late-content rule (private-repos.md §2–§4, §8) | `EpochKeys::derive`, `ref_name_hash`, `open_content`, `is_late` | `private_kdf__*`, `private_ref_hash__*`, `private_doc_seal__*`, `private_doc_open__*`, `private_hedge__*` | diff --git a/docs/errors.md b/docs/errors.md index cccec248a..5c8a2632c 100644 --- a/docs/errors.md +++ b/docs/errors.md @@ -193,7 +193,7 @@ Two cases have their own message: - "the key stored on this computer holds no encryption key": your identity usually has one (`dg auth keys list`; identities from `dg auth new`, the bridge and the web app have key 4), but the key source in use does not hold its private half: a limited key stored by an older `dg`, or with `--signing-only`, is a signing key only. - "`` has no encryption key" (`dg collab add` to a private repository): the member you named has no enabled `ENCRYPTION` key on their identity. -**What to do:** for the first, sign in again, replacing the key in use (`dg auth status` shows its id, and its `Private:` line prints the command): `dg auth login --replace `, or `dg auth login --mnemonic --replace ` with the 12-word recovery phrase if you have no identity file (a `dg auth new` identity). It registers a new limited key, stores your encryption key beside it and disables the old key; the master key is used once and not stored. For one command, point `DASH_FORGE_KEY` at the identity file. If the identity has no ENCRYPTION key at all, `dg auth keys add --encryption` adds one, derived from the recovery phrase (one identity update signed by the master key). A member you are adding does this themselves, or uses Settings → Keys → Enable private repos in the web app. See [identity and keys](guides/identity-and-keys.md#encryption-key-private-repositories). +**What to do:** for the first, sign in again, replacing the key in use (`dg auth status` shows its id, and its `Private:` line prints the command): `dg auth login --replace `, or `dg auth login --mnemonic --replace ` with the 12-word recovery phrase if you have no identity file (a `dg auth new` identity). It registers a new limited key, stores your encryption key beside it and disables the old key; the master key is used once and not stored. For one command, point `DASH_FORGE_KEY` at the identity file. If the identity has no ENCRYPTION key at all, `dg auth keys add --encryption` adds one, derived from the recovery phrase (one identity update signed by the master key). A member you are adding does this themselves, or uses Settings → Private repos → Enable private repos in the web app. See [identity and keys](guides/identity-and-keys.md#encryption-key-private-repositories). ## E307 @@ -231,21 +231,23 @@ Two cases have their own message: ## E311 -**No key has been shared with you yet.** You're a member of this public repository and it has members-only content, but no maintainer has shared its key with your encryption key. This happens when you were added by an older Forge build that did not share the key. You can still read everything public, and the members-only items show as placeholders. +**You're a member, but no key has been shared with you yet.** This public repository has members-only content, and no maintainer has shared its key with your encryption key. This happens when you were added by an older Forge build that did not share the key. You can still read everything public, and the members-only items show as placeholders. -**What to do:** a maintainer's client shares it the next time they open the repo; from the command line a maintainer runs `dg repo keys repair /`. If your identity has no encryption key yet, add one first: `dg auth keys add --encryption`. +**What to do:** ask a maintainer to share it: **Repair** on the repo page, or `dg repo keys repair /`. Nothing shares it automatically. If your identity has no encryption key yet, add one first: `dg auth keys add --encryption`. ## E312 **Members-only content is not turned on.** You asked for members-only content (an issue, comment or review only members can read) in a public repository where no maintainer has turned it on. -**What to do:** a maintainer runs `dg repo members enable /`, which sets up a key for the current members (the command shows the cost first). Until then, post it publicly or ask a maintainer. +**What to do:** a maintainer runs `dg repo members enable /`, which sets up a key for the current members (the command shows the cost first). Until then, post it publicly or ask a maintainer. See [Turn on members-only content](security/audiences.md#turn-on-members-only-content). ## E313 **Members-only.** This issue or pull request is members-only: only members of the repository can read it. Everyone can see that it exists, its number, who opened it and when; nothing else. -**What to do:** ask the repository's owner to add you as a member (`dg collab accept /` first, your consent). If you are a member already, see [E311](#e311). +**What to do:** ask the repository's owner to add you as a member (`dg collab accept /` first, your consent). If you are a member already, see [E311](#e311). If your key is protected by a passphrase and there is no terminal to ask for it, set `DASH_FORGE_PASSPHRASE` and try again. [Who can read what](security/audiences.md) explains members-only content. + +`dg issue view` and `dg pr view` don't stop with E313: they show such an item as a row (`#3 · members-only issue by @alice · open`) and exit 0. E313 comes from commands that need its content, such as commenting on it or checking it out. ## E401 diff --git a/docs/guides/README.md b/docs/guides/README.md index 40d1149e1..64ef6d99c 100644 --- a/docs/guides/README.md +++ b/docs/guides/README.md @@ -11,6 +11,8 @@ Task-oriented guides for using Dash Forge. For how it is built, see the [documen | [Bring your own storage](bring-your-own-storage.md) | keep pack bytes in your own R2, B2, S3, Storj, self-hosted S3 or IPFS instead of on Platform, from the CLI or the browser | | [Storage on your home NAS](home-nas-storage.md) | run RustFS or Garage (or kubo) on a Synology, TrueNAS or Linux box, publish it safely with a Cloudflare Tunnel, and keep a second copy | | [Collaborating](collaborating.md) | add members, work with issues, pull requests, reviews, merges, releases and webhooks | +| [Who can read what](../security/audiences.md) | keep issues, comments and reviews of a public repository members-only, and know who can read them, what everyone still sees and what can still leak | +| [Environments](environments.md) | keep configuration and secrets outside git, encrypted for your maintainers or members, and inject them with `dg env run` | | [CI and check runs](ci.md) | enrol a CI runner with a key that can only report check runs, report results with `dg ci report`, and see them on commits and PRs | | [Self-host a CI runner](self-host-runner.md) | run a repository's `.forge/workflows` on your own machine with `forge-runner` (nektos/act in Docker), safely | | [Identity and keys](identity-and-keys.md) | understand your identity and limited keys, back it up, recover it, and keep keys safe | @@ -30,7 +32,9 @@ Also: These guides describe what is on `master` today. Features that are specified but not built yet are marked **Coming soon**, and nothing marked that way works yet. The main ones: -- editing files in the browser, and browser merges for private repositories (the CLI has them). +- editing files in the browser, and browser merges for private repositories (the CLI has them); +- in the web app: choosing Members for a new issue or comment, turning members-only content on, the members-only rows non-members see, **View as public**, and Settings → Environments (`dg` has the rest); +- members-only pull requests, branches and releases, Specific people, and making members-only discussion public. Dash Wallet sign-in is built. With today's wallets it works only in the iOS app pointed at Forge's key-exchange contract on sakura (not yet tried on a real device), and on testnet once Forge is deployed there: see [Identity and keys](identity-and-keys.md#signing-in-with-the-dash-wallet-app-what-works-today). diff --git a/docs/guides/collaborating.md b/docs/guides/collaborating.md index 72f8a62a0..cf6c61474 100644 --- a/docs/guides/collaborating.md +++ b/docs/guides/collaborating.md @@ -3,11 +3,13 @@ Everything a team does on Forge is a signed document on Dash Platform: who may push, issues, comments, pull requests, reviews, merges and releases. There is no server in the middle to ask. Consensus decides who may write, and every client computes the same state from the same documents. 1. [Collaborators](#collaborators) -2. [Issues](#issues) -3. [Pull requests](#pull-requests) -4. [Releases](#releases) -5. [From the web app](#from-the-web-app) -6. [Webhooks and CI](#webhooks-and-ci) +2. [Private repositories](#private-repositories) +3. [Members-only content in a public repository](#members-only-content-in-a-public-repository) +4. [Issues](#issues) +5. [Pull requests](#pull-requests) +6. [Releases](#releases) +7. [From the web app](#from-the-web-app) +8. [Webhooks and CI](#webhooks-and-ci) The commands below take a repository as `/`, where `` is the owner's **identity id** (base58) or **DPNS username** (`alice` or `alice.dash`, resolved with a proof-verified DPNS read). A bare `` means one of your own repositories. Every argument naming an identity — `dg repo list --owner`, `dg collab add`/`remove`, `dg issue --author`/`--assignee`, `dg pr request-review`, `dg ci runner add`/`revoke` — accepts either form; a name is resolved once per process and cached. @@ -17,11 +19,11 @@ Reading a public repository needs no identity: `dg repo view`, `dg repo list --o ## Collaborators -There are four roles. Consensus enforces what each role can write: a write the role does not allow is refused by Platform, and Forge's apps refuse it before you pay for it. Counting approvals and offering readers only on private repositories are rules Forge apps enforce: every app applies them alike ([Who enforces what](#who-enforces-what)). +There are four roles. Consensus enforces what each role can write: a write the role does not allow is refused by Platform, and Forge's apps refuse it before you pay for it. Counting approvals is a rule Forge apps enforce: every app applies it alike ([Who enforces what](#who-enforces-what)). | Role | `--role` | Can | Closest GitHub role | |---|---|---|---| -| Reader | `reader` (alias `read`); **private repositories only** | Read the repository (it receives the key). Otherwise what anyone can do: open issues and PRs, comment and review, and as an author close or reopen their own issues and PRs, mark their own PRs draft or ready, request reviews on them and resolve their threads. | Read | +| Reader | `reader` (alias `read`) | Read the repository's encrypted content: a private repository, or a public repository's [members-only content](#members-only-content-in-a-public-repository) (it receives the key). Otherwise what anyone can do: open issues and PRs, comment and review, and as an author close or reopen their own issues and PRs, mark their own PRs draft or ready, request reviews on them and resolve their threads. | Read | | Triage | `triage` | Close, reopen and lock any issue or PR; label, assign, set milestones, request reviews and resolve review threads; create labels and milestones. **Not**: push, merge, mark a PR draft or ready, change a PR's base, dismiss reviews, pin, post check runs, or re-run checks. | Triage | | Writer | `writer` (default) | Everything triage can, plus push to unprotected branches, merge, mark draft or ready, change a PR's base, dismiss reviews, pin, post check runs, and re-run checks. | Write | | Maintainer | `maintainer` | Everything a writer can, plus protected branches, releases, repository settings (`config`, branch policy), webhooks and hiding comments. | Maintain, and most of Admin | @@ -30,7 +32,7 @@ The repository owner alone adds and removes members, and edits the description a Anyone, member or not, can open issues and PRs, comment and review. Approvals count toward a branch policy only from maintainers and writers: a triage member's or reader's approval is shown as **not counted**, and their request for changes does not block. Imported issues and comments (a mirror's provenance and upstream numbers) are trusted from the same people. -A public repository has no readers: everyone can read it already. A member holds one writer document, so changing between writer, triage and reader replaces it: `dg collab add` with the new `--role` deletes the old document and writes the new one (their acceptance stands, so they need not accept again), and the web app's Settings → Members has **Change role** on public repositories. On a private repository `dg collab add` changes the role the same way without rotating the key, since the member stays a member; in the web app, remove the member and add them again, which rotates it as every removal does. +On a public repository everyone can read the public content already, so a reader is for its [members-only content](#members-only-content-in-a-public-repository): someone who should follow the members-only discussion without pushing or merging. `dg collab add --role reader` works on public repositories too, and the web app offers Reader there too. A member holds one writer document, so changing between writer, triage and reader replaces it: `dg collab add` with the new `--role` deletes the old document and writes the new one (their acceptance stands, so they need not accept again), and the web app's Settings → Members has **Change role** on public repositories. On a private repository `dg collab add` changes the role the same way without rotating the key, since the member stays a member; in the web app, remove the member and add them again, which rotates it as every removal does. Adding a collaborator is two steps: the owner adds them, and the collaborator accepts. Consensus admits a `writer`/`maintainer` document only when it names the member's own `consent` document for the repo (`member_consent`), so nobody can be made a member, or spammed with an invitation, without agreeing first. @@ -45,7 +47,7 @@ dg collab remove / --role writer If the owner runs `dg collab add` before the invitee has accepted, it is refused before anything is signed: *"`` has not accepted membership of `` yet"*, with the fix to ask them to run `dg collab accept`, then add them again. `dg collab add / --wait 300` instead waits (printing that it is waiting) up to that many seconds for the acceptance to land, then adds them; with no `--wait` it checks once. `dg collab accept --withdraw` withdraws an earlier acceptance (a membership already granted stands until the owner removes it). -From the web app, the invitee opens the repository's **invite link** (Settings → Members, on public and private repos alike) and clicks **Accept invitation**; the owner's Settings → Members lists **Pending invitations** (accepted, not added yet) with a role picker (writer, triage, maintainer, and on a private repository reader) and an **Add** button for each, and shows who is still waiting to accept after a refused add. +From the web app, the invitee opens the repository's **invite link** (Settings → Members, on public and private repos alike) and clicks **Accept invitation**; the owner's Settings → Members lists **Pending invitations** (accepted, not added yet) with a role picker (writer, triage, maintainer and reader) and an **Add** button for each, and shows who is still waiting to accept after a refused add. Adding or removing a collaborator is a write by the repository owner, signed with the owner's HIGH key. @@ -147,7 +149,7 @@ dg repo keys status /secret # epochs, who holds a key, pendi Leave the description empty if the project's purpose is itself sensitive. -**Every member needs an encryption key.** Private repositories wrap the key to each member's identity `ENCRYPTION` key. `dg collab add` checks the member has one and stops before writing anything if not ([`E306`](../errors.md#e306)); they add one with `dg auth keys add --encryption`, or Settings → Keys → **Enable private repos** in the web app. +**Every member needs an encryption key.** Private repositories wrap the key to each member's identity `ENCRYPTION` key. `dg collab add` checks the member has one and stops before writing anything if not ([`E306`](../errors.md#e306)); they add one with `dg auth keys add --encryption`, or **Settings → Private repos → Enable private repos** in the web app. **Readers.** A reader (`--role reader`) holds the key like any member and can read everything, and can write only what anyone can (issues, PRs, comments and reviews, all sealed). Their approvals do not count. Like any member, a reader could copy what they read. @@ -167,6 +169,45 @@ Not supported for private repositories yet ([`E207`](../errors.md#e207)): forks --- +## Members-only content in a public repository + +A public repository can keep some of its discussion **members-only**: issues, comments and reviews that only its members can read, beside everything public. Its code, branches and pull requests stay public. Everyone can still see that something was posted, by whom and when. [Who can read what](../security/audiences.md) explains the audiences, exactly what stays public, and what can still leak. + +```sh +dg repo members enable / # a maintainer, once; shows the cost first +dg repo members status / # on or off, can you read it, who has no key yet +dg issue create / --members --title "…" --body "…" +dg issue comment / 12 --members --body "…" +dg pr comment / 7 --members --body "…" +dg pr review / 7 --approve --members --body "…" +``` + +**Turning it on** shares a members key with every member who has an encryption key: about 0.0004 DASH plus about 0.0007 DASH per member (about 0.004 DASH for 5 members). Members without an encryption key are listed. They get the key once they set one up (`dg auth keys add --encryption`) and a maintainer runs `dg repo keys repair`. A member who asks for members-only content before it is on gets [`E312`](../errors.md#e312). In the web app, a maintainer chooses **Turn on members-only content**; the sheet shows the same cost first. + +**Replies follow what they answer.** Without `--members`, a comment on a members-only issue, or a reply to a members-only comment, is members-only. A public reply inside a members-only conversation is refused before anything is signed. Edits keep the audience. + +**Reading.** Members read members-only items in `dg issue view`/`list` and `dg pr view`/`list`, marked "members-only". Everyone else sees `#3 · members-only issue by @alice · open`, "3 members-only comments hidden, shown as placeholders (you're not a member of alice/shop)", and lists that say how many rows they can't read ("Issues 3 (1 members-only; only members of alice/shop can read them)"). In `--json`, every item has `"audience"` and `"readable"`. A `dg` key protected by a passphrase is asked for on the terminal. Without a terminal (or with `--json`, and no `DASH_FORGE_PASSPHRASE`), a member sees the items as locked instead. A removed member still reads what was posted before the removal. + +**From the web app**, members read members-only issues, comments and reviews after one unlock per tab, and a reply in a members-only conversation stays members-only. Choose **Members** on a composer's audience chip for a new issue or comment; everyone else sees members-only rows and placeholders, and **View as public** shows you what they see. + +**A members-only review counts.** Its verdict is public, so an approval counts toward the branch policy for everyone, member or not, while its text stays members-only. Older Forge builds don't count it, and may refuse a merge an up-to-date build allows ([`E804`](../errors.md#e804)). Update to see and count members-only reviews. + +**Adding and removing members** works as on a private repository, keyed on whether the repository has members-only content: + +- `dg collab add` shares the key with the new member (about 0.0007 DASH more). They read everything members-only, including what was posted before they joined. A member with no encryption key is added anyway and can do everything public. They get the key after they set one up and a maintainer runs `dg repo keys repair`. +- `dg collab remove` changes the key (about 0.0007 DASH per remaining member, plus about 0.0006 DASH), and says so before you confirm: new members-only issues, comments and reviews will be unreadable to them, and what they could already read stays readable to them. +- A role change between writer, triage and reader keeps the key: every role holds it, readers included. +- The web app's **Settings → Members** does the same. +- Change members only with an up-to-date Forge. A member added by an older build has no key yet and sees [`E311`](../errors.md#e311) until a maintainer shares it: **Repair** on the repo page, or `dg repo keys repair`. Nothing shares it automatically. A member removed by an older build keeps reading new content until `dg repo keys repair` changes the key. `dg repo keys status` shows both. + +**CI runners are not members.** A runner key (`dg ci runner add`) reports check runs and never receives the members key. If you make a runner's identity a reader, it reads everything members-only. + +**Environments.** A repository's configuration and secrets can be kept outside git, encrypted for its **Maintainers** or its **Members**: see [Environments](environments.md). + +**Not yet.** Members-only pull requests, branches, code and releases, specific people, and making members-only discussion public are coming later. Search doesn't look inside members-only issues you can't read. + +--- + ## Issues Anyone with an identity and some credits can file an issue. Fees are the spam floor. @@ -413,6 +454,7 @@ A review records the commit it was made on, which is the PR's head at the time. - Only reviews from current writers and maintainers count. - Only reviews on the PR's **current** head count. When the head moves, older reviews go stale: `dg pr view` marks them, and tells a reviewer "new commits since your review". - A reviewer's newest approve or request-changes review is the one that stands. +- A [members-only](#members-only-content-in-a-public-repository) review counts like any other, for everyone: its verdict is public, only its text is members-only. Anyone can post a review. A non-member's approve or request-changes is written, shown on the PR, and labelled "approved (not a member)" or "changes requested (not a member)" — it never counts toward the branch policy's required approvals, and `dg` says so. @@ -588,6 +630,7 @@ On forge.dashhq.org, signed in with a limited key ([Identity and keys](identity- | Merge a PR (see below) | | | Create a repository (public or private), or fork one, with a cost preview; sync a fork with its parent (fast-forward) | Syncing a fork whose branch has commits of its own (open the pull request it offers) | | Add and remove members (owner) | | +| Read and write members-only issues, comments and reviews (members, after one unlock per tab), and turn members-only content on (maintainers) | Members-only pull requests and branches (not yet in Forge) | | Publish a release with assets, creating its tag when it does not exist (maintainers) | | | Star repositories and follow people | | | See your repositories, issues, PRs and stars in **Explore**, and new activity in **Notifications** | | diff --git a/docs/guides/identity-and-keys.md b/docs/guides/identity-and-keys.md index cd2ec4fcd..7282dde95 100644 --- a/docs/guides/identity-and-keys.md +++ b/docs/guides/identity-and-keys.md @@ -44,7 +44,7 @@ An identity file from the bridge, the web app or `dg auth new` has five keys, al | 1 | AUTHENTICATION | HIGH | Signing documents: pushes, issues, comments, reviews, releases. | | 2 | AUTHENTICATION | CRITICAL | What HIGH does. Forge uses it only when the file has no HIGH key. | | 3 | TRANSFER | CRITICAL | Moving credits to another identity, or withdrawing them. | -| 4 | ENCRYPTION | MEDIUM | Private repositories (see [Encryption key](#encryption-key-private-repositories)), and decrypting webhook secrets addressed to a relay you run. | +| 4 | ENCRYPTION | MEDIUM | Private repositories and members-only content in public ones (see [Encryption key](#encryption-key-private-repositories)), and decrypting webhook secrets addressed to a relay you run. | | 5+ | AUTHENTICATION | HIGH | [Limited keys](#limited-keys): what `dg`, `git push` and the web app sign with day to day. | What each tool signs with: @@ -146,9 +146,13 @@ If the **MASTER** key or the 12 words leak, rotating does not help: whoever has A private repository encrypts its content under a repository key, and each member gets that key wrapped (encrypted) to their identity's **ENCRYPTION** key. Without one, nobody can add you to a private repository and you cannot create one. Identities from `dg auth new`, the bridge and the web app carry key 4 for this. +The same key reads [members-only content](../security/audiences.md) in public repositories: issues, comments and reviews only a repository's members can read. Without it you can still be a member of a public repository and do everything public, and you receive the members key once you set one up and a maintainer runs `dg repo keys repair`. Writing members-only content without one stops with [`E306`](../errors.md#e306): set up your encryption key first. + **Using it from the CLI.** Reading or writing a private repository needs the ENCRYPTION key's private half. `dg auth login` (from the identity file or the recovery phrase) and `dg auth new` store it beside the limited signing key, where the limited key is kept (the keychain, or a passphrase-sealed file), as the web app's "Enable private repos" does: private repositories work with no master key on disk. `dg auth status` shows it (`Private:`). `--signing-only` (or `--insecure-plaintext`, which would write it in the clear) stores the signing key alone; a key stored by an older `dg` is one too, and signing in again with `--replace ` adds it (`dg auth status` prints the command). `dg auth keys add` keeps the encryption keys the key it replaces holds. Without it, private-repo commands stop with [`E306`](../errors.md#e306); `DASH_FORGE_KEY=` works for one command. -**An identity without one** can add it: +`dg` uses the same stored key for members-only content in public repositories. It opens the key only for a repository with members-only content that you are a member of, so other reads never ask for a passphrase. A key protected by a passphrase is asked for on the terminal; with no terminal (or with `--json`) and no `DASH_FORGE_PASSPHRASE`, you see the members-only items as locked, with a note saying how to unlock. + +**An identity without one** can add it. This is **Set up your encryption key**: ```sh dg auth keys add --encryption @@ -175,7 +179,7 @@ It runs the rekey of [private-repos.md §5.2](../security/private-repos.md#52-en The key `dg` stores beside your limited key (`dg auth login`) gets the new key too. A repository counts as moved only when a fresh read shows your wrap for its current epoch on the new key. If one is not, every old key stays enabled and nothing is lost. Run the command again: each run adds a fresh key and treats every enabled encryption key as old, since a lost device may have held an earlier run's key too. Other computers and browsers need the new key: sign in again with the words, or in the web app add it from **Settings → Private repos**. -**In the web app** this will be **Settings → Keys → Enable private repos**, with the web release of private repositories. +**In the web app**, **Settings → Private repos → Enable private repos** stores your encryption key in this browser's vault: from your recovery phrase, your identity file or the key itself, checked against your identity first, or **Register a new key** for an identity that has none. A wallet sign-in stores it for you ([below](#signing-in-with-the-dash-wallet-app-what-works-today)). The vault keeps every encryption key you give it, and **Add another encryption key** adds one more. --- @@ -272,6 +276,7 @@ What to expect with today's wallets: - **Two approvals (iOS).** The iOS wallet grants a key for one contract per approval. The first covers repositories and pushes (forge-core); the first sign-in also asks you to approve a second code that adds that key to your identity. The first issue, PR, review or star asks for one more approval (**Approve issues and pull requests**), for forge-collab, plus, the first time, a second code that registers that key. Android's key is not bound to any contract, so it covers both at once (see the next point). - **No spending limit or expiry.** The wallets register the key without a budget or an expiry (Android's is not even bound to a contract), and Platform cannot add limits to such a key later. The app warns about it on the confirmation step and in Settings, and prefers a passkey to protect it. **Replace with a limited key** (your identity file or 12 words, once) swaps it for a normal budgeted key and disables the wallet's keys in the same update. - **A disabled wallet key cannot be replaced by the wallet.** The wallet derives the same key every time, so after you disable it the wallet cannot give Forge a fresh one. Forge refuses that sign-in; use Import instead. +- **Your encryption key comes with the wallet sign-in.** The first time the wallet approves Forge, it registers an encryption key beside Forge's key, and Forge keeps that key in this browser's vault under the same passkey or passphrase. A returning sign-in brings the same key again. Each first approval for another Forge contract (**Approve issues and pull requests** on iOS) registers one more, and the vault keeps every one, so private repositories and members-only content open with whichever key they were shared with. After a reload, one unlock in the tab opens all of them, for every repository. If your identity's current encryption key came from somewhere else (`dg auth keys add --encryption`, say), Forge says *"Your encryption key is held elsewhere. Import it under Settings → Private repos."* If a repository was shared only with a key from another approval that this browser doesn't hold, the repository says *"Your encryption key came with another approval in your wallet. Approve it again under Settings → This browser's key to read private repos."* - **Check the identity yourself.** The answer does not prove who sent it: on the wallets' contract, whoever answers the QR code first is the identity Forge shows. Compare the username and identity id with the wallet's approval screen, which shows the username and the first 7 and last 5 characters of the id. Forge warns when the identity has no username, a username less than a day old, or is not the one this browser already knows. A request expires after 5 minutes; keep the QR code private. Drafts of the wallet-side fixes (group-scoped, limited grants; a signature that proves which identity answered) are in [`docs/upstream/`](../upstream/app-connect-responder-auth.md), for the owner to file with dashpay. @@ -292,7 +297,7 @@ CI gets one pasteable value, `DASH_FORGE_KEY=dfk1:::`). --- diff --git a/docs/security/audiences.md b/docs/security/audiences.md new file mode 100644 index 000000000..1607de653 --- /dev/null +++ b/docs/security/audiences.md @@ -0,0 +1,230 @@ +# Who can read what: Public, Members and Specific people + +Everything in a Dash Forge repository has an **audience**: Public, Members or Specific people. You can always choose a narrower audience for something new. You widen it only by publishing it or making it public, and that can't be undone. + +This page explains what each audience means, what a public repository can keep **members-only** today, who can read it, what everyone can still see, and what members-only content does not protect against. For a wholly private repository, where everything is encrypted, see [Private repositories](../guides/collaborating.md#private-repositories). + +1. [The three audiences](#the-three-audiences) +2. [What can be members-only today](#what-can-be-members-only-today) +3. [Who can read members-only content](#who-can-read-members-only-content) +4. [Turn on members-only content](#turn-on-members-only-content) +5. [Post and read members-only content](#post-and-read-members-only-content) +6. [What it costs](#what-it-costs) +7. [What everyone can still see](#what-everyone-can-still-see) +8. [Who can learn what](#who-can-learn-what) +9. [What can still leak](#what-can-still-leak) +10. [What this does not protect against](#what-this-does-not-protect-against) +11. [Older Forge builds](#older-forge-builds) +12. [Errors](#errors) +13. [Words used on this page](#words-used-on-this-page) + +--- + +## The three audiences + +| Audience | Who reads it | Changes when members change | Available | +|---|---|---|---| +| **Public** | Everyone | — | today | +| **Members** | Every current member of the repository: maintainers, writers, triage members and readers. Members added later read it too, including what was posted before they joined. | yes | today, for issues, comments, reviews and environments | +| **Specific people** | A list the writer picks, members or not. The writer is always on it. | no | **coming later**. Environments already use one fixed list, **Maintainers**: the repository's maintainers when each change is saved. | + +The Members audience is encrypted on your computer or in your browser before anything is sent. Dash Platform stores the encrypted text. Nobody without the repository's members key can read it: not Platform nodes, not storage providers, not Forge's developers. + +A **private** repository is different: everything in it is encrypted, code included, and it has no public side. This page is about members-only content inside a **public** repository. + +## What can be members-only today + +| Content | Members-only today? | +|---|---| +| Issues | yes | +| Comments on issues and pull requests | yes | +| Reviews of a pull request (the review's text; its verdict stays public, [below](#what-everyone-can-still-see)) | yes | +| [Environments](../guides/environments.md): configuration and secrets kept outside git | yes: **Members** or **Maintainers** | +| Pull requests themselves, branches, commits and code | **coming later**. Everything you push to a public repository is public. | +| Releases | **coming later** | +| Label and milestone definitions | no, they stay public. Which label or milestone a members-only issue has is encrypted. | + +A reply follows what it answers: a comment on a members-only issue, or a reply to a members-only comment, is members-only too. A members-only comment on a public issue or pull request is fine. A public reply inside a members-only conversation is refused before anything is signed. + +Who something is for is fixed when it is posted. Editing a members-only comment or issue keeps it members-only, and Forge refuses to edit a public one into a members-only one. Making members-only discussion public later is **coming later**. Until then, post a new public comment. + +## Who can read members-only content + +| Who | Reads members-only content? | +|---|---| +| The owner and maintainers | yes | +| Writers and triage members | yes | +| Readers | yes. On a public repository the **reader** role exists for exactly this: someone who should read the members-only discussion without pushing or merging. | +| A CI runner | **no**, by default. A runner's key reports check runs and is not a membership. If you make the runner's identity a reader, it reads everything members-only, like any reader. | +| Someone added later | yes, everything, including what was posted before they joined | +| Someone removed | what was posted **before** the removal, for good. Nothing posted afterwards. Encryption can't take back what was already shared. | +| Anyone else | no. They see that something was posted, by whom and when ([below](#what-everyone-can-still-see)). | + +Removing a member changes the key, so what is posted afterwards is unreadable to them. Adding a member shares the key with them. Both happen in `dg collab add` and `dg collab remove`, which show the cost first ([Collaborating](../guides/collaborating.md#members-only-content-in-a-public-repository)). + +Every member needs an **encryption key** on their identity to receive the members key. Identities made with `dg auth new`, the web app or the bridge have one. If yours does not, set up your encryption key with `dg auth keys add --encryption` ([Identity and keys](../guides/identity-and-keys.md#encryption-key-private-repositories)). A member without one can still do everything public, and gets the key once they add one and a maintainer runs `dg repo keys repair`. + +## Turn on members-only content + +A maintainer turns it on once per repository: + +```sh +dg repo members enable / +``` + +Before anything is signed it asks "Turn on members-only content?", says what members will be able to do and that everyone can still see that something was posted, by whom and when, and shows the cost of setting up keys for the current members (each later removal costs about the same again). It also warns that people using older Forge builds will see fewer things until they update ([below](#older-forge-builds)). + +It shares the members key with every current member who has an encryption key, and lists those who don't have one yet. `dg repo members status /` says whether it is on, whether you can read it, and who is still waiting for the key. A member who asks for members-only content in a repository where it is off is told to ask a maintainer ([E312](#e312)). + +Turning it on cannot be undone, and it changes nothing that is already public. + +In the web app, a maintainer chooses **Turn on members-only content** (in the audience picker or under Settings → Members); the sheet shows the cost for the current members first. + +## Post and read members-only content + +From `dg`, add `--members`: + +```sh +dg issue create / --members --title "Spam wave from new accounts" --body "…" +dg issue comment / 12 --members --body "The reporter is the same person as in #9." +dg pr comment / 7 --members --body "This touches the fraud rules." +dg pr review / 7 --approve --members --body "LGTM, see the fraud-rule note." +``` + +Without `--members` the context decides: inside a members-only conversation a reply is members-only. Members read members-only items in `dg issue view`, `dg issue list`, `dg pr view` and `dg pr list` like any other, marked "members-only". With `--json`, every item carries `"audience"` (`"public"` or `"members"`) and `"readable"`. + +Anyone else sees a row and a count, never the text: + +```text +$ dg issue view alice/shop 3 +#3 · members-only issue by @alice · open + +$ dg pr view alice/shop 7 +... +3 members-only comments hidden, shown as placeholders (you're not a member of alice/shop) +``` + +`dg issue view` adds a line saying only members can read it, and `dg pr view --comments` shows each members-only comment as a placeholder with its author and time. Lists say how many rows you can't read: "Issues 3 (1 members-only; only members of alice/shop can read them)". + +**In the web app**, members read members-only issues, comments and reviews after unlocking once in the tab, and a reply in a members-only conversation stays members-only. Every composer has an audience chip (**Public** or **Members**); a reply inside a members-only conversation can only be members-only. Everyone else sees members-only rows and placeholders and a "#N · members-only" page instead of the content, and members can check what the public sees with **View as public**. Before a public post that quotes members-only text, the web asks you to confirm. + +**Search** looks only at what you can read. `dg search` tells you how many members-only issues it could not search. + +**Notifications.** The web app's notifications and the webhooks `forge-relay` delivers say that something happened, never what was said. Encrypted comments and reviews from people who are not members are not shown and notify nobody. An issue anyone opens as members-only still gets its numbered row and a notice, since its number is public. Whoever runs a notification service gets the same rules ([members-only notifications](../hosting/members-only-notifications.md)). + +## What it costs + +Measured on devnet sakura: + +| Action | Cost | +|---|---| +| Turn on members-only content | about 0.0004 DASH, plus about 0.0007 DASH for each member who gets the key (about 0.004 DASH for 5 members) | +| Add a member to a repository with members-only content | the usual membership write, plus about 0.0007 DASH to share the key | +| Remove a member | the usual delete, plus a key change: about 0.0007 DASH per remaining member and about 0.0006 DASH more | +| Post a members-only issue, comment or review | 0 to 8 % more than the same thing in public | +| Save an environment change | about 0.0025 DASH | + +Reading costs nothing. + +## What everyone can still see + +Encryption hides **what was said**. It does not hide **that something was said**. For every members-only item, everyone can see: + +- that it exists, who posted it, and when (and when it was edited); +- its size, rounded up to 64 bytes; +- that it is members-only; +- that its author was a member when they posted it. + +And per kind of item: + +| Item | Everyone can see | Only members can read | +|---|---|---| +| A members-only comment or review on a public issue or pull request | which issue or pull request it is on, and which comment it replies to; an inline comment's line numbers and commit; **a review's verdict** (approved, changes requested, commented), which counts toward the branch policy for everyone | the text, an inline comment's file path, the review's text | +| A members-only issue | its number ("#12 · members-only"); when it was opened, closed, reopened or locked, and by whom; that a label or milestone was set or someone assigned, and **who** was assigned; the counts that include it | the title, the body, the names of its labels and milestone | +| An environment | that the repository has environments and how many; for each change, who made it, when, and its size rounded up to 512 bytes; for a Maintainers environment, how many people it was sent to | its name, the names, types and notes of its entries, and every value | +| The repository | that members-only content is on; when the members key changed; who shared the key with whom; the member list and roles (public on every repository) | the key | + +A review's verdict is public on purpose: everyone agrees on whether a pull request has its approvals, so a member and a non-member see the same merge button. A pull request's author who is not a member sees "Changes requested by @bob" and cannot read why. Add one public line saying what to fix. + +## Who can learn what + +| Who | Reads members-only content | Learns anyway | +|---|---|---| +| The public, any Dash Platform node, explorers and indexers | no | everything in [What everyone can still see](#what-everyone-can-still-see) | +| Your storage provider (for long members-only text and environments) | no | file sizes, and when files are read | +| A notification service or relay that is not a member, including the hosted one | no | that something happened, by whom, when, and on which issue or pull request | +| A hosted read-only mirror of the code | no | the public repository only | +| A current member | yes | | +| A removed member | everything posted before the removal, forever | sizes and timing afterwards | +| A CI runner | no, unless you make its identity a reader | | +| Someone who builds a modified Forge | no | they can post encrypted text, as anyone may. No member's Forge app shows a comment or review from someone who was not a member. An issue gets its numbered row, like any members-only issue. | +| A tampered copy of the web app that you unlock | everything you can read | [Verify the app you loaded](../guides/verify-the-app.md), or run your own copy | + +## What can still leak + +- **Everything in [What everyone can still see](#what-everyone-can-still-see).** Who talks, when, how much, and on which issue can say a lot. Leave out what the timing alone would give away. +- **What members copy.** Any member can copy, quote or screenshot what they read. Quoting a members-only comment into a public reply publishes the quoted text. +- **What removed members kept.** They keep everything posted before the removal. Removing someone protects only what comes after. +- **Past values in a Members environment.** Everyone who becomes a member later can read every value ever stored there, including past values. Keep production credentials in a **Maintainers** environment, and rotate a secret at its source when someone leaves ([Environments](../guides/environments.md#removing-a-member)). +- **Code.** Everything pushed to a public repository is public, forever, even if you delete it later. The push helper refuses some files that look like secrets and warns about others ([Secrets in a push](../guides/quick-start.md#secrets-in-a-push)), but it cannot know everything. Keep secrets in an environment instead. +- **Your encryption key.** It reads every private repository and every members-only conversation you belong to. Keep it like your signing keys, and replace it after a lost device ([Identity and keys](../guides/identity-and-keys.md#replacing-it-after-a-lost-device)). +- **Mentions.** Mentioning someone who is not a member in a members-only comment tells them nothing they can read, but they may learn that something was posted. + +## What this does not protect against + +Forge stops accidents, not intent. A member who copies members-only text by hand into a public issue, a commit, an email or anywhere else has published it, and no check can stop that. + +When members-only branches arrive (coming later), the same holds for code: the checks before a push stop a member from publishing members-only commits by accident. A member who copies files by hand into a public branch, or who pushes with `git push --no-verify`, is out of scope. + +## Older Forge builds + +People using older Forge builds see fewer things until they update. Nothing leaks and nothing breaks: + +- members-only items are left out without saying why, and counts that include them are not labelled; +- a members-only issue opened by its number reads as "not found" (an older `dg` says E102); +- an older web app may describe members-only items as "encrypted by someone who is not a member". That is wrong. Update; +- an older build does not count a members-only review's approval, so it may refuse a merge an up-to-date build allows ([E804](../errors.md#e804)). Never the reverse. **Update to see and count members-only reviews.** + +Change members only with an up-to-date Forge (`dg` or the web app), so the key follows every change: + +- a member added by an older build has no key yet, and sees [E311](#e311). Nothing shares it automatically: a maintainer chooses **Repair** on the repository page or runs `dg repo keys repair`; +- a member removed by an older build can still read new members-only content until the key changes. `dg repo keys status` flags it, and `dg repo keys repair` changes the key. + +## Errors + +### E311 + +**No key has been shared with you yet.** You're a member, but no maintainer has shared the members key with your encryption key. This happens when an older Forge build added you. You can still read and do everything public. The members-only items show as placeholders. + +Forge says: "You're a member, but no key has been shared with you yet. Ask a maintainer to share it: Repair on the repo page, or `dg repo keys repair`." + +**What to do:** ask a maintainer to share it. They choose **Repair** on the repository page (it shows the cost first), or run `dg repo keys repair /`. If your identity has no encryption key yet, set one up first: `dg auth keys add --encryption`. + +### E312 + +**Members-only content is not turned on.** You asked for a members-only issue, comment or review in a public repository where no maintainer has turned it on. + +**What to do:** a maintainer runs `dg repo members enable /` (it shows the cost first). Otherwise, post it publicly, or ask a maintainer to turn it on. + +### E313 + +**Members-only.** That issue or pull request is members-only, and you can't read it. Everyone can see that it exists, its number, who opened it and when. `dg issue view` and `dg pr view` show that as a row and exit normally. E313 comes from commands that need the content, such as commenting on it or checking it out. + +**What to do:** ask the repository's owner to make you a member (run `dg collab accept /` first: that is your consent). If you are a member already, see [E311](#e311). If your key is locked (a key protected by a passphrase, with no terminal to ask for it), set `DASH_FORGE_PASSPHRASE` or run the command in a terminal. + +A members-only write by someone who is not a member stops with [E601](../errors.md#e601) before anything is signed. A member whose identity has no encryption key gets [E306](../errors.md#e306): set up your encryption key first. Every code is also in [Error codes](../errors.md). + +## Words used on this page + +| Word | Means | +|---|---| +| **Public** | Everyone can read it. | +| **Members** | Every current member of the repository, and everyone who becomes one later. | +| **members-only** | Readable by Members only. "A members-only comment." | +| **Specific people** | A list the writer picks (coming later). | +| **Maintainers** (environments) | The maintainers when the change was saved. | +| **Turn on members-only content** | What a maintainer does once per repository (`dg repo members enable`). | +| **Set up your encryption key** | What each person does once per identity (`dg auth keys add --encryption`). | +| **Publish**, **Make public** | Widening code or discussion to everyone (coming later). It can't be undone. | + +How it is built: [Private repositories §17](private-repos.md#17-mixed-repositories-members-only-content-in-a-public-repository) and [forge-v2.md §5](../contracts/forge-v2.md#5-private-repositories). diff --git a/docs/security/private-repos.md b/docs/security/private-repos.md index b9f6c9efe..2f5eea6a2 100644 --- a/docs/security/private-repos.md +++ b/docs/security/private-repos.md @@ -286,7 +286,7 @@ Keys: the **sender** is the wrapping maintainer's identity key with purpose `ENC ### 5.2 Encryption keys: derivation, custody, blast radius, rekey -Most identities have no `ENCRYPTION` key. Adding one is an `IdentityUpdate` signed by the master key: `dg auth keys add --encryption`, or the web app's Settings → Keys → "Enable private repos". +Most identities have no `ENCRYPTION` key. Adding one is an `IdentityUpdate` signed by the master key: `dg auth keys add --encryption`, or the web app's Settings → Private repos → "Enable private repos" ("Register a new key"). **Derivation.** Where the identity comes from a seed, the encryption private key is derived under a hardened Forge-specific branch of the identity's key tree whose last element is a hardened **key index** `k'`: the exact path constants are fixed when `dg auth keys add --encryption` is implemented, but the invariant is normative: `k` starts at 0, every rekey uses `k+1`, and the path is hardened at every level, so a leaked key `k` gives no information about key `k+1` and a mnemonic restore can re-derive every key it ever had by walking `k` upward until it finds no matching public key on the identity. An identity created from a raw key gets a random encryption key and is told to back it up. Contract bounds on the key are a hint only; writers use the highest-id **enabled** `ENCRYPTION` key of the recipient and record the id they used. @@ -294,7 +294,7 @@ Most identities have no `ENCRYPTION` key. Adding one is an `IdentityUpdate` sign **Blast radius, stated plainly.** ECDH is symmetric, so an identity's encryption private key decrypts **every wrap it received and every wrap it sent**. For a plain member that is every epoch of every private repo they belong to. For a maintainer it is additionally every epoch key they ever wrapped for anyone: a compromised maintainer encryption key exposes every repo they maintain. The UI says: "This key can read every private repo you're a member of, and every key you've handed out as a maintainer." -**Rekey flow** (`dg auth keys rotate --encryption`; web Settings → Keys → "Replace my private-repo key"). Order matters: +**Rekey flow** (`dg auth keys rotate --encryption`; the web app's Settings → Devices & keys → "Lost a device?" gives that command, and Settings → Private repos adds the new key to a browser). Order matters: 1. Add the new encryption key `k+1` (master-key `IdentityUpdate`). Do **not** disable the old key yet. 2. For every repo where the identity is a **current maintainer** (its `maintainer` documents, via the `memberId` index): run the rotation of §5.5 with the new key as the self-wrap recipient (the new epoch key is wrapped to every member's highest enabled encryption key, the rotator's included). @@ -890,7 +890,7 @@ Two independent security reviews read revision 1 of this section: a Fable review ## 17. Mixed repositories: members-only content in a public repository -A **public** repository may hold **members-only** content beside its public content: issues, comments and reviews only its members can read (DESIGN `mixed-visibility/DESIGN.md` §4.1, phase 1). This section is the rule level; the `enc` v0x03 / v0x04 envelopes, their key commitment and padding are §4.x. Nothing here changes a private repository. +A **public** repository may hold **members-only** content beside its public content: issues, comments and reviews only its members can read (DESIGN `mixed-visibility/DESIGN.md` §4.1, phase 1). This section is the rule level; the `enc` v0x03 / v0x04 envelopes, their key commitment and padding are §4.x. Nothing here changes a private repository. The user-facing account, with what stays public and what can still leak, is [Who can read what](audiences.md); the contract-level summary is forge-v2.md §5.1. ### 17.1 The members key ("lane 0") @@ -908,7 +908,7 @@ Vectors `mixed_anchor__*`. Every membership change keys on **"this repository ha ### 17.3 Reads are per document -Whether a document is sealed is read from the document (`enc` present, and `enc[0]`), never from the repository. A plaintext document is read as it is whatever keys the reader holds; a sealed one is opened with the members key, and a reader who cannot open it gets a **placeholder**: its id, author, time, number (an issue's or PR's), audience and `asMember`, and the reason (not a member; a member whose key source holds no encryption key; a member the key was not shared with yet, **E311**; or keys that do not open it). A public repository's keys are loaded only when a sealed document is met, and an outsider never gets an error (E306, E307) or "not found" for one: an issue or PR read by number is "members-only" (**E313** where an error is the only answer). Placeholders are shown for documents carrying `asMember` or a thread's root; the rest are hidden and counted (DESIGN D14). +Whether a document is sealed is read from the document (`enc` present, and `enc[0]`), never from the repository. A plaintext document is read as it is whatever keys the reader holds; a sealed one is opened with the members key, and a reader who cannot open it gets a **placeholder**: its id, author, time, number (an issue's or PR's), audience and `asMember`, and the reason (not a member; a member whose key source holds no encryption key; a member the key was not shared with yet, **E311**; a member whose key is locked, with no way to ask for its passphrase; or keys that do not open it, filed with a `badTag` or `CommitMismatch` under "not encrypted for this repo"). `dg issue view` / `dg pr view` of a members-only issue or PR prints its row and exits 0. A removed member's client still loads the members key when the reader holds a wrap from an earlier epoch, so content written before the removal stays readable to them, as in a private repository. A public repository's keys are loaded only when a sealed document is met, and an outsider never gets an error (E306, E307) or "not found" for one: an issue or PR read by number is "members-only" (**E313** where an error is the only answer). Placeholders are shown for documents carrying `asMember` or a thread's root; the rest are hidden and counted (DESIGN D14). ### 17.4 Approvals (D15) @@ -919,5 +919,20 @@ A members-only review's plaintext `verdict` counts for **every reader** when it - **Audience fixed at creation.** An edit keeps the document's audience: a members-only document is re-sealed as a whole; a plaintext edit of it, and a members-only edit of a public document, are refused before signing (vectors `mixed_edit__*`). Consensus `noPlain` admits an `enc` → `body` replace of a `comment`, so this is the clients' rule. - **A child's audience is a subset of its parent's.** Before sealing a comment, a reply, a review or an event value, the writer reads the parent (the target issue or PR, and a reply's thread root): a members-only comment on a public thread is allowed, a public reply to a members-only comment or a public comment on a members-only issue is refused, and an event value is sealed exactly when its target is. Without a request the default is the parent's audience. - **`asMember` on every sealed write by a member**, and a write whose proof consensus refuses is never retried without it when it is sealed (a member removed meanwhile is told so). -- **No members-only text at rest or in public storage.** The create journal's fingerprint is keyed for anything not public, and a members-only text that does not fit its field is refused (its full text would otherwise be stored as a public artifact) until kind-70 sealed long bodies exist. +- **No members-only text at rest or in public storage.** The create journal's fingerprint is keyed for anything not public. A members-only pending review that `dg` keeps on disk is the draft sealed under the members key (`{"dashForgeMembersReviewDraft":1,"sealed":…}`), never plaintext; the web keeps a members-only draft in memory only. A members-only text that does not fit its field (the v0x03 room, 32 bytes less than v0x01's) is a **kind-70** artifact (§17.6) in `dg`; the web refuses it before signing until it writes kind 70 too. It is never stored as a public kind-6 artifact. - Only members write members-only content: a non-member is refused before signing, a repository without a members key with **E312**, a member without a shared key with **E311**. + +### 17.6 Artifacts: pack manifest kinds + +`packManifest.kind` is an open integer (forge-v2.md §2); readers skip a kind they do not know, so the kinds below need no contract change (DESIGN D6). Sealed artifacts are DFPK files (§3): version `0x01` under an epoch key, or `0x02` with the specific-people slot header (§3.7). + +| Kind | What | Status | +|---|---|---| +| 7 | reveal bundle: per-object keys that make members-only documents public | reserved (phase 2) | +| 8 | **environment snapshot**: one environment's canonical JSON, padded to 512-byte buckets, sealed as DFPK `0x01` under the members key at the write epoch (audience Members) or DFPK `0x02` to the current maintainers' encryption keys, the writer first (audience Maintainers). `supersedes` names earlier counted snapshots of the same environment. Readers check the bytes against the owner-signed `packHash` before decrypting, and count a snapshot only when its `$ownerId` is a current maintainer (DESIGN D24); vectors `env_snapshot__*` | used | +| 9 | environment registry | reserved (phase 4) | +| 10 | branch grant (the keys of one members-only branch, sealed to one recipient) | reserved (phase 3) | +| 64 + k | the members-only (sealed) form of plain kind k in a public repository: 64 git pack, 65 object locator, 66 flat index, 67 history index, 68 release assets, 69 history version lists | reserved (phase 3) | +| 70 | **members-only long body** (64 + 6): the full text of a members-only issue, comment or review longer than its field, sealed as DFPK `0x01` under the members key at the write epoch, re-read before the write. A members-only field's trailer resolves only to a kind-70 copy, a public field's only to kind 6. The reader checks `packHash`, then the late-content rule on the copy's `$ownerId` and height, then opens it with any epoch it holds | used by `dg`; the web refuses members-only long text for now | + +In a private repository every artifact is sealed under its usual kind (§3): kinds 64–70 are for the members-only side of a public repository only. `dg repo view` counts kind 0 only; `dg storage status` lists every kind and names 70 `members-only-long-body`.