From adda3794fc63e029c76bf82f3fba1a5422e4faf0 Mon Sep 17 00:00:00 2001 From: Paul d'Aoust Date: Mon, 3 Feb 2025 15:30:17 -0800 Subject: [PATCH] improve membrane proof language in build guide --- src/pages/build/callbacks-and-lifecycle-hooks.md | 6 +++++- src/pages/build/genesis-self-check-callback.md | 10 +++++----- 2 files changed, 10 insertions(+), 6 deletions(-) diff --git a/src/pages/build/callbacks-and-lifecycle-hooks.md b/src/pages/build/callbacks-and-lifecycle-hooks.md index 7cfc7e42f..d9ceb41d2 100644 --- a/src/pages/build/callbacks-and-lifecycle-hooks.md +++ b/src/pages/build/callbacks-and-lifecycle-hooks.md @@ -30,7 +30,11 @@ You don't need to write this callback by hand; you can let the `hdk_entry_types` ### Define a `genesis_self_check` callback -There's a moment in a cell's life, after it's been instantiated but before it's connected to its network, where it's published data that it can't fully validate. This data is their [**genesis records**](/concepts/3_source_chain/#source-chain-your-own-data-store). However, a `genesis_self_check` callback can guard against basic errors that would get an agent banned from a network. Read the [Genesis Self-Check Callback](/build/genesis-self-check-callback/) page for more info. +There's a moment in a cell's life, after it's been instantiated but before it's connected to its network, where it's published data that it can't fully validate. This data is their [**membrane proof**](/concepts/3_source_chain/#source-chain-your-own-data-store), an optional chunk of data that can serve as a joining code for the network. You can write validation rules for it just like any other record, allowing existing agents to reject newcomers with invalid credentials. + +This record can't be validated, however, because it's written to the source chain before the agent joins the network, and the `validate` callback can only be run after they've joined. + +However, if you write a `genesis_self_check` callback, it can guard against some basic user entry errors that would get an honest agent banned from a network. Read the [Genesis Self-Check Callback](/build/genesis-self-check-callback/) page for more info. ## Coordinator zomes diff --git a/src/pages/build/genesis-self-check-callback.md b/src/pages/build/genesis-self-check-callback.md index baa3ec0af..b4e18b520 100644 --- a/src/pages/build/genesis-self-check-callback.md +++ b/src/pages/build/genesis-self-check-callback.md @@ -3,24 +3,24 @@ title: "Genesis Self-Check Callback" --- ::: intro -When an agent hasn't yet joined a network, but has written their [**membrane proof**](/concepts/3_source_chain/#source-chain-your-own-data-store) to their [**source chain**](/concepts/3_source_chain/), they may not be able to fully validate it, but still need a way to do basic pre-validation before joining the network. This helps prevent them from being rejected from the network. +To enforce access control for a network, a DNA can require a [**membrane proof**](/concepts/3_source_chain/#source-chain-your-own-data-store), which is a piece of data that gets entered by the user and written to their [**source chain**](/concepts/3_source_chain/). The `genesis_self_check` function can guard against user entry error and help prevent them from being banned from the network accidentally. ::: ## Membrane proof: a per-agent joining code for a network -While Holochain requires an agent to have the correct [DNA hash](/build/dnas/#dnas-the-rules-of-the-game-for-a-network) to join a network, a DNA can impose extra access control via a **membrane proof**, a small piece of data that acts at the level of an individual agent. It should be generated by an authority and given to the user, then a runtime like the Holochain Launcher will ask them for it when a hApp is installed. It's written to the source chain as an [`AgentValidationPkg`](https://docs.rs/holochain_integrity_types/latest/holochain_integrity_types/action/enum.Action.html#variant.AgentValidationPkg) record. +If your network needs to enforce membership control, your [`validate` callback](/build/validate-callback/) can check the contents of the [`AgentValidationPkg`](https://docs.rs/holochain_integrity_types/latest/holochain_integrity_types/action/enum.Action.html#variant.AgentValidationPkg) record. This [**genesis record**](/resources/glossary/#genesis-records) contains data that's entered by the user on app installation. If validators find an invalid proof, they can ban the unauthorized agent from joining the network. A membrane proof can be basic, like per-agent invite codes, or it can be something complex like a [JSON Web Token (JWT)](https://jwt.io/) signed by an agent that has authority to admit members. -!!! info Access control isn't implemented yet +!!! info Membership control isn't implemented yet This feature is not fully implemented. Currently, validators merely record validation failure for a membrane proof and supply it on request. Our plan is to use membrane proof validation outcomes to admit or block communications from peers. !!! ## The need for basic pre-validation -The use cases we just explored require access to network data in order to fully validate the membrane proof. But an agent can't self-validate their own membership proof at cell startup, because they haven't joined the network. This creates a problem; they may accidentally type their membrane proof wrong, but won't find out until they try to join the network and immediately get ejected. +Most useful membrane proofs will require access to network data in order to fully validate them. But an agent can't self-validate their own membership proof at genesis time, because they haven't joined the network yet. This creates a minor problem; they may accidentally type or paste their membrane proof wrong, but won't find out until they try to join the network and get ejected. -To reduce the risk, you can define a `genesis_self_check` function that checks the membrane proof before network communications start. This function is limited --- it naturally doesn't have access to DHT data. But it can be a useful guard against basic data entry errors. +To reduce the risk, you can define a `genesis_self_check` function that checks the membrane proof before network communications start. This function is limited --- it naturally doesn't have access to DHT data -- but it can be a useful guard against basic data entry errors. ## Define a `genesis_self_check` callback