docs: closely held vs widely held #1248
Conversation
Deploying documentation with
|
| Latest commit: |
806577a
|
| Status: | ✅ Deploy successful! |
| Preview URL: | https://116caa06.documentation-7tp.pages.dev |
| Branch Preview URL: | https://rs-closely-vs-widely-held.documentation-7tp.pages.dev |
|
Cloudflare deployment logs are available here |
rabi-siddique
force-pushed
the
rs-closely-vs-widely-held
branch
2 times, most recently
from
ca459c3 to
d58e012
Compare
| @@ -79,6 +79,20 @@ e.g., only giving the `entryGuard` the ability to increment the counter. | |||
|
|
|||
| This limits the damage that can happen if there is an exploitable bug. | |||
|
|
|||
| ### Widely Shared vs. Closely Held | |||
|
|
|||
| #### Widely Shared Resources | |||
There was a problem hiding this comment.
"Resources"? Why introduce another term? Why not stick with "capabilities"?
There was a problem hiding this comment.
link the usages of the 2 terms under "access control with objects" please
separation of powers between the publicFacet, which is expected to be shared widely, and the creatorFacet, which is closely held.
|
|
||
| #### Widely Shared Resources | ||
|
|
||
| In the context of Agoric's object capability model, "widely shared" refers to resources or capabilities that are accessible to a large portion of the code within a system. For example: |
There was a problem hiding this comment.
This makes it sound like the term is not used outside of Agoric. It dates back at least as far as Keykos in 1977
Closely Held
Said of a capability or a class of capabilities; but typically one of a kind, such as the domain tool. Closely held keys are designed to be held by some small fixed set of programs in order, typically, to insure the safety of the entire system.
-- http://www.cap-lore.com/CapTheory/Glossary.html
There was a problem hiding this comment.
Wow. Thanks for sharing this!
|
|
||
| In the context of Agoric's object capability model, "widely shared" refers to resources or capabilities that are accessible to a large portion of the code within a system. For example: | ||
|
|
||
| - **agoricNames**: This component serves as a read-only name service, which means it can be accessed by most parts of the system. Since it only allows data to be read and not modified, it poses minimal risk and can be safely made widely available. |
There was a problem hiding this comment.
please link agoricNames to the more definitive description under Name Services
|
|
||
| On the other hand, "closely held" resources are restricted and only accessible to specific parts of the system that require them to function effectively: | ||
|
|
||
| - **agoricNamesAdmin**: Known as the write facet of the name service, this component allows modifications to the data in `agoricNames`. Given its capability to alter critical system data, access to `agoricNamesAdmin` is limited to only those parts of the system that have a legitimate need for write access. This precaution helps to prevent potential misuse or errors that could compromise the system. |
| @@ -79,19 +79,19 @@ e.g., only giving the `entryGuard` the ability to increment the counter. | |||
|
|
|||
| This limits the damage that can happen if there is an exploitable bug. | |||
|
|
|||
| ### Widely Shared vs. Closely Held | |||
| ### [Widely Shared vs. Closely Held](/guides/zoe/contract-access-control.html#access-control-with-objects) | |||
There was a problem hiding this comment.
sorry; I meant the other way around: there are uses of these terms under "access control with objects". Please link those uses to the definitions here.
Also: Headings should not be links.
There was a problem hiding this comment.
I made the update. Lmk what you think
| In the object capability model, "widely shared" refers to capabilities that are accessible to a large portion of the code within a system. For example: | ||
|
|
||
| - [**agoricNames**](/guides/integration/name-services.html#agoricnames-agoricnamesadmin-well-known-names): This component serves as a read-only name service, which means it can be accessed by most parts of the system. Since it only allows data to be read and not modified, it poses minimal risk and can be safely made widely available. | ||
| Similarly, in [Access Control with Objects](guides/zoe/contract-access-control.html#access-control-with-objects), this concept is mirrored by the **publicFacet**, which exposes safe-to-share functionality publicly. |
There was a problem hiding this comment.
That works.
What I was suggesting, though, is links from uses to definitions, so that when the reader is in "Access Control with Objects" and comes across use of the terms "shared widely" and "closely held", they can follow links to definitions in this section. Just like the uses of agoricNames and agoricNamesAdmin are linked to definitions in "Name Services".
There was a problem hiding this comment.
Ohh that makes sense. Let me update. Silly me
rabi-siddique
force-pushed
the
rs-closely-vs-widely-held
branch
3 times, most recently
from
5a3f145 to
caa9010
Compare
rabi-siddique
force-pushed
the
rs-closely-vs-widely-held
branch
from
caa9010 to
806577a
Compare
The PR introduces the concepts of "widely shared" and "closely held" resources under the Principle of Least Authority (POLA) section.