Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
14 commits
Select commit Hold shift + click to select a range
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -29,6 +29,7 @@ Members-only content in public repositories, Environments and the secret scan. P
- **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=<fingerprint>` 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."
- **Wallet sign-in with App Connect v2: one approval for all of Forge.** Where the network runs protocol 14 and Forge is deployed (devnet sakura today), the wallet tile comes first and shows an App Connect v2 request: the wallet adds one key for this browser that works on every Forge contract, capped at 0.05 DASH of spending and expiring after 90 days (a wallet may offer other limits), so the extra approvals of the older exchange are not asked for. The phone link returns to a new `/connect/` page, and the sign-in checks the wallet again when the tab regains focus. A key a wallet granted is renewed in that wallet (**Renew in your wallet**, in the low-funds banner, the top-up sheet and Settings → This browser's key); the identity file or recovery phrase still works. If your wallet's build has no App Connect v2, **Show the older code** gives today's request. A v2 sign-in does not bring an encryption key: set up private and members-only content in Settings. We know of no released Dash Wallet that speaks App Connect v2 yet; the [wallet sign-in notes](docs/design/wallet-login.md#app-connect-v2-one-approval-for-all-of-forge) say what works today.
- **Passkeys for other devices (web app).** **Settings → Devices & keys → Passkeys for other devices** adds a passkey that holds this browser's key, encrypted to it, on Platform. On another device, **Sign in with a passkey** brings that sign-in over: the same key and budget, checked against your identity before it is used. A passkey moves a session, it doesn't recover an account: when the key expires or is disabled it stops working, and you renew with your identity file, recovery phrase or wallet (a session restored from a passkey offers both **Renew in your wallet** and **Renew with identity file**). Keys without a spending limit or an expiry stay on the device that holds them, because the encrypted copy is public on Platform for good. Your encryption key is included only if you tick it, with a warning that it can't be taken back. After signing in, the web app offers a passkey once (twice at most, never after **Not now**). Revoking or disabling a key offers to remove the passkeys that hold it. Adding one costs about 0.0005 DASH from the key's budget; signing in is free. It works at forge.dashhq.org only. **It does nothing yet:** the controls stay hidden until forge-meta on the network has the new `vaultEntry` type, which is a pending forge-meta update on devnet sakura. See [Passkeys: the threat model](docs/security/passkey-vault.md) and [identity and keys](docs/guides/identity-and-keys.md#passkeys-for-other-devices).

### Changed

Expand Down
13 changes: 9 additions & 4 deletions crates/forge-core/src/layout.rs
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,8 @@
//! here instead of hard-coding one, so the map lives in exactly one place.
//!
//! DESIGN rev 4.1 D44 adds a fourth contract, forge-meta, registered last: `repoKey`, `ban`,
//! `label`, `topic`, `packMirror`, `profile` and `follow` ([`META_TYPES`]) move there. The
//! `label`, `topic`, `packMirror`, `profile` and `follow` ([`META_TYPES`]) move there, and
//! `vaultEntry` (UPDATE-2, the passkey vault) exists there only. The
//! deployment record says which layout a network has (`v2.forgeMeta` present,
//! [`ForgeIds::meta`]), so one build serves sakura's three-contract set and four-contract sets:
//! [`ForgeIds::contract_of`] is the layout-aware map, [`ForgeContract::of`] the three-contract
Expand Down Expand Up @@ -86,15 +87,18 @@ pub const COMMUNITY_TYPES: [&str; 12] = [
/// The types forge-meta holds on a four-contract set (D44). On a three-contract set they stay
/// in [`CORE_TYPES`] (`label`, `topic`, `packMirror`), [`COLLAB_TYPES`] (`repoKey`, `ban`) and
/// [`COMMUNITY_TYPES`] (`profile`, `follow`). None of them is read by a rule, total or derived
/// index of its old contract, so the move changes no consensus rule.
pub const META_TYPES: [&str; 7] = [
/// index of its old contract, so the move changes no consensus rule. `vaultEntry` (UPDATE-2) is
/// the exception: `build.py` builds it with the four-contract layout only, so it has no
/// three-contract home and [`ForgeContract::of`] knows no contract for it.
pub const META_TYPES: [&str; 8] = [
"repoKey",
"ban",
"label",
"topic",
"packMirror",
"profile",
"follow",
"vaultEntry",
];

/// The listed types a contract build may leave out: RC2's fused star (C1, a `build.py` flag)
Expand Down Expand Up @@ -415,7 +419,8 @@ mod tests {
assert_eq!(four.contract_id_of(t), Some("META"), "{t}");
assert_eq!(four.home(t), "META", "{t}");
assert_ne!(three.contract_id_of(t), Some("META"), "{t}");
assert!(three.contract_id_of(t).is_some(), "{t}");
// (vaultEntry, UPDATE-2, is a four-contract type: no home in the three-contract set)
assert_eq!(three.contract_id_of(t).is_some(), t != "vaultEntry", "{t}");
}
for (t, old) in [
("repoKey", "COLLAB"),
Expand Down
19 changes: 18 additions & 1 deletion docs/contracts/forge-v2.md
Original file line number Diff line number Diff line change
Expand Up @@ -111,7 +111,22 @@ The mainnet registration (`build.py --mainnet`, flag `layout_meta`; dash-forge-q

The mainnet forge-core also gains `pushGrant` (B1, §9.1): a maintainer's grant letting a Bot member (`writer.role` 4) push to one exact members-only ref or under one public ref prefix, for at most 90 days. Clients write and read it from phase 4E (`docs/security/private-repos.md` §24): `dg bot allow --push`, `renew`, `suspend`, `resume` and `revoke --push`; a bot's push stamps `r` 4, `pp`/`pg` and `grantor`; readers mark a bot's push outside its access client-side.

Devnet sakura keeps the three-contract set, and clients take the layout from the deployment record: `v2.forgeMeta` present means four contracts, and the seven types are read and written there; absent, they stay in their old homes. One build serves both (phase M-B: `forge-core::layout` `ForgeIds::contract_of` and `home`, forge-web `lib/layout.ts` `contractKindOfType` and `lib/repo/source.ts` `contractOf`, the seed scripts' `contractOn`). The cost previews follow: a signer's first write to forge-meta pays its contract nonce even when it has written the type's old home, and a key bound to forge-meta alone is a wallet grant of its own ("labels, topics and profiles").
**`vaultEntry` (UPDATE-2, the passkey vault).** forge-meta also holds one type that no other layout has: `vaultEntry`, a passkey-sealed bundle of a session's keys, one per (owner, WebAuthn credential), so a new device can sign in with a passkey and open the keys the signed-in session stored. `build.py` defines it in forge-community (flag `passkey_vault`, in `UPDATE2_FLAGS`) and `META_TYPES` moves it to forge-meta; it is built with the four-contract layout only, because forge-community's three-contract build would grow to 18,385 B (over the 17,832 B ceiling) with 1,989 B of room (under `ROOM_MIN`). No rule, total or reference to another type reads it, so it changes no consensus rule, and protocol 14 lets an update add it (it is a new type with its own index, §9.1). It is covered by the same group membership as the rest of forge-meta, so no key binding or group trust changes. A three-contract network has no `vaultEntry` (the clients' layout answers "no contract holds it").

| Property | Shape | Note |
|---|---|---|
| `credentialId` | byte array, 16 to 255 B | the WebAuthn credential id; **immutable**; in the unique index |
| `recipientKey` | `bytes`, 32 B | the HPKE recipient public key the passkey's PRF output derives; **immutable** |
| `version` | integer, 1 to 255 | the entry format |
| `authKeyId` | `u32`, `refersTo` `identityPublicKey` (`identityProperty` `$ownerId`, `keyRequirements {purpose: authentication}`) | the owner's authentication key that slot 0 of the bundle stands for; Platform checks it is one on create and on any replace that changes it |
| `enc` | `bytes`, 32 B | the HPKE encapsulated key |
| `sealed` | byte array, 32 to 256 B | the ciphertext. Forge writes one format of 256 B (240 B padded plus the 16 B tag). An update can still loosen its bounds (lower `minItems`, raise `maxItems`), but never make it fixed-length |

`documentsMutable` and `canBeDeleted` are both true: re-sealing is a replace of `enc`, `sealed`, `version` and `authKeyId` (`credentialId` and `recipientKey` are listed under `immutable`, so a replace cannot move an entry to another passkey or recipient, and the ciphertext's AAD binds both), and removing a passkey is a delete, which refunds its storage deposit. `required`: `$createdAt`, `$updatedAt` and every property above; `additionalProperties` is false. One unique index, `byCredential [$ownerId, credentialId]`, serves the sign-in lookup (both bound) and an owner's list (the `$ownerId` prefix). The shorthand form (`mainnet_shorthand`) writes `recipientKey` and `enc` as `{"type": "bytes", "size": 32}`; `credentialId` and `sealed` vary in length and keep the long form.

Size: forge-meta serializes to 7,684 B (6,870 B without it), its create transition to 7,790 B (6,976 B), which leaves 12,690 B of room; the fee schedule's registration fee for the contract goes from 0.36 to 0.39 DASH (one more type and one more index; the per-byte part is not in that figure). **Estimated fees** (not measured on Forge; scaled from Yappr's sakura measurements of the same document shape, to be re-measured by the live test): a first entry about 46 to 50 M credits (about 0.0005 DASH), a later entry about 28 to 31 M, a re-seal about 2 to 3 M, a delete refunds about 23 to 35 M, and a sign-in reads only, so it is free. Forge's 256 B ciphertext is 80 to 160 B larger than Yappr's, which adds about 2 to 4 M credits at 27,400 credits per byte ([economics.md](../economics.md)). All of it comes out of the signed-in key's budget.

A devnet may run the three-contract set (devnet sakura did until it moved to the four-contract set on 2026-10-17), and clients take the layout from the deployment record: `v2.forgeMeta` present means four contracts, and the seven types are read and written there; absent, they stay in their old homes. One build serves both (phase M-B: `forge-core::layout` `ForgeIds::contract_of` and `home`, forge-web `lib/layout.ts` `contractKindOfType` and `lib/repo/source.ts` `contractOf`, the seed scripts' `contractOn`). The cost previews follow: a signer's first write to forge-meta pays its contract nonce even when it has written the type's old home, and a key bound to forge-meta alone is a wallet grant of its own ("labels, topics and profiles").

Shared shapes (`id`, `hid`, `oid`, `h32`, `refName`, `branch`, `title`, `body`, `enc`, `vis`, `member`, …) are in `schemaDefs` and referenced with `$ref`. A document type may use each `$defs` entry **once**: rs-dpp's depth walker treats a second `$ref` to the same definition in one type as a cycle (`InvalidJsonSchemaRefError`). That is why `packHash` uses `hid`, an identical copy of `id`. The same goes for the `integer` shape of a key id named by `encryptedFor` or `keyIdProperty`, which must be inline (the parser's `is_key_id_schema` resolves `$ref` against the document schema, which has no `$defs`). Repeats are inlined for these reasons. Every `enc` is at least 29 bytes (INV-11: the smallest envelope).

Expand Down Expand Up @@ -845,6 +860,8 @@ An update may add only optional properties, `enum` values appended at the end, a

**Size.** With UPDATE-1 the three contracts serialize to 17,462 / 17,633 / 17,513 B: 54, 225 and 105 B over the 17,408 B target (§7), all under the 17,832 B ceiling. The signed update transitions are about 17.5–17.7 KB of the 20,480 B limit, which leaves about 2.7 KB for any later update.

**UPDATE-2** (the passkey vault) is one more `DataContractUpdate`, of forge-meta alone: `vaultEntry` (§2, forge-meta), a new type with its own unique index and a `refersTo` to the owner's own authentication key, nothing on an existing type. It is the flag `passkey_vault` (`UPDATE2_FLAGS`, off in the registered v1 set; `stale_registered` turns it off with UPDATE-1's). On a network that is not registered yet (testnet, mainnet) it is part of the registration set and changes forge-meta's sha256, which the owner signs again; on devnet sakura, which registered forge-meta without it (`4CyD…`, source `04627b52…`), it ships as `deploy-v2.mjs --update meta` and `contract-validate --expect-update` accepts the new forge-meta as an update of the registered one (`ALLOWED (DataContractUpdate v1 -> v2)`; run by hand against `git show ec3c86f12:forge-contracts/contracts/mainnet/forge-meta.json`, the file sakura registered, since no `registered/devnet-sakura/` copy is frozen for CI). Its vectors (`vaultEntry` cases of the `U2` item: shapes, bounds, the immutable `credentialId` and `recipientKey`, the re-seal, the index) are generated for the four-contract set (`vectors.py --mainnet`), and the committed three-contract vectors only assert that the type is absent there.

**The mixed-visibility items (mainnet only).** dash-forge-qa `design/mixed-visibility/DESIGN.md` rev 4.1 §8.3 adds the layout and eleven items to `MAINNET_FLAGS`, in its order. Each is off in every devnet build and on with `build.py --mainnet`; `build.NEEDS` refuses a combination that cannot register (a `where` naming a property another item adds, or B1 without the room forge-meta leaves). Row numbers are DESIGN §8.2's. A refusal is 10422 (the first broken rule in name order), 40127 (a `where` mismatch) or 40120 (no document found), as M-C checks live.

| # | Flag | Item | Contract | What consensus enforces | Until mainnet |
Expand Down
2 changes: 1 addition & 1 deletion docs/deploying-to-a-network.md
Original file line number Diff line number Diff line change
Expand Up @@ -26,7 +26,7 @@ Four contracts, in one contract group (`dash-forge`) that has an owner and **no
| 1 | `forge-core` | repositories, members (`writer`, `maintainer`, `consent`), packs, refs, releases, config, `pushGrant`. Its create transition also creates the contract group. |
| 2 | `forge-collab` | issues, pull requests, reviews, comments, transitions |
| 3 | `forge-community` | `authorEvent`, `checkRun`, `event`, `milestone`, `policy`, `runner`, `star`, `watch`, `webhook` |
| 4 | `forge-meta` | `ban`, `follow`, `label`, `packMirror`, `profile`, `repoKey`, `topic` ([forge-v2.md §2](contracts/forge-v2.md#forge-meta-mainnet-set-only)) |
| 4 | `forge-meta` | `ban`, `follow`, `label`, `packMirror`, `profile`, `repoKey`, `topic`, `vaultEntry` ([forge-v2.md §2](contracts/forge-v2.md#forge-meta-mainnet-set-only)) |

The order is fixed. Each contract takes the deployer's next identity nonce, the contract and group ids derive from those nonces, and each later contract's schema names the ids of the ones registered before it. [forge-v2.md §8](contracts/forge-v2.md#8-deploying) has the details.

Expand Down
1 change: 1 addition & 0 deletions docs/economics.md
Original file line number Diff line number Diff line change
Expand Up @@ -93,6 +93,7 @@ All in DASH, **measured on devnets** (to be re-measured on testnet); fiat figure
| Fork a repo | ~0.01 DASH for a small repository and 0.03 for a 36-pack one: one small manifest per pack and one ref update per branch; the parent's packs are referenced, never re-uploaded | same |
| Push 100 KiB source delta (~30 KiB packed) | about 0.015–0.02 DASH (~$0.45–0.60): 0.33–0.36 DASH/MiB for the packed bytes plus ~0.004–0.011 for the manifests, ref update and history index. Permanent | ~0.004–0.0055 DASH (~$0.12–0.17): manifests and the ref update only |
| 1,000 issues + 5,000 comments over a year | **~3.1–4.5 DASH** (~$95–135) for short bodies (issues 0.0006–0.001 each, comments 0.0005–0.0007 each; more with long bodies). Issues are permanent, comments refundable on delete | same (always on Platform) |
| Add a passkey for other devices, then sign in with it elsewhere | **~0.0005 DASH** for an identity's first (estimate: Yappr's 46–50M credits plus ~2–4M for Forge's larger 256-byte entry), ~0.0003 for each later one; re-sealing after a key change ~0.00003; removing one refunds ~0.0002–0.0003; signing in is free. Paid from the browser key's budget ([passkey vault](security/passkey-vault.md)) | same |
| Remove one member from a 50-member repository with members-only content | ~0.035 DASH: the key is changed for the 49 who remain ([guides/costs.md](guides/costs.md#members-only-and-private-content)) | same |
| Force-push away 10 MiB of history, then repack | nothing recovered; the repack adds a deposit for the consolidated pack | delete the old objects in your bucket |
| Deployer: register the production set (once per network) | **~1.86 DASH for the four contracts** (0.5968 + 0.3963 + 0.5063 + 0.3636), measured on a Platform v5 devnet, and 1.873 DASH on testnet (2026-10-26); ~1.73 DASH for the three-contract devnet set ([Deploying Forge to a network](deploying-to-a-network.md#4-what-it-costs), [forge-v2.md §7](contracts/forge-v2.md#7-measured-size-and-cost)) | same |
Expand Down
14 changes: 14 additions & 0 deletions docs/guides/costs.md
Original file line number Diff line number Diff line change
Expand Up @@ -244,6 +244,20 @@ Packs are git packfiles: delta-compressed and deflated, typically 20–35% of th

---

### Passkeys for other devices

A passkey's entry is one small stored item, written with this browser's key (so it comes out of that key's budget, like any write). These are estimates from Yappr's measurements on a development network plus the extra bytes of Forge's fixed-size entry, not yet measured on testnet; the live test (`lib/auth/passkey-vault.live.test.ts`) prints what each step really cost.

| Action | About | Notes |
|---|---|---|
| First passkey on an identity | 0.0005 DASH | builds the identity's passkey list, so it costs more than the next ones |
| Each later passkey | 0.0003 DASH | |
| Update a passkey after a key change | 0.00003 DASH | a replace of its entry |
| Remove a passkey | refunds about 0.0002–0.0003 DASH | deleting returns the deposit |
| Sign in with a passkey | free | reads only |

At most 10 passkeys per identity. An entry is always the same size, whatever keys it holds.

## Platform or your own bucket

Pack bytes are almost all of a repository's size, so where you keep them decides the cost:
Expand Down
Loading
Loading