Read-Write Permissions On KV Maps¶
To allow governance audit we ensure that all governance actions can be viewed and understood from the ledger, and signed by members. To support this CCF distinguishes governance tables from application tables, and restricts which tables can be read from and written to in different execution contexts.
Table Namespaces¶
There are 3 categories of table defined:
Governance tables. These begin with a
public:ccf.gov
prefix, indicating that they are public (their contents are not encrypted in the ledger), and in theccf.gov
namespace. These should only be modified by constitution-controlled governance actions.Internal tables. These begin with a
ccf.internal
orpublic:ccf.internal
prefix, indicating that they are in theccf.internal
namespace, and may be public or private. These can be considered a lower-level subset of governance tables, though some are also modified by node-triggered operations such as signatures, rather than governance actions. These are only modified by framework code, and should never be altered by user code.Application tables. This includes any other table name. These are the tables that application endpoints should modify.
Warning
Table names are case sensitive. So public:CCF.gov.users
(upper-case “CCF”) is an application table, not a governance table. Similarly, PUBLIC:table
is a private application table.
Note
All other tables in the ccf
namespace are reserved for future use, so attempting to access any table beginning ccf.
which is not in the governance or internal namespace will result in an error.
Execution Contexts¶
There are multiple possible contexts in which developer-specified code may execute within a CCF node:
Pre-approval governance context. These pieces of code may read from the KV to make decisions, but may not make any modifications to it, as they represent pending, unapproved operations. Specifically, this context applies:
when evaluating member ballots
when evaluating the constitution’s
validate
functionwhen evaluating the constitution’s
resolve
function
Post-approval governance context. These pieces of code run only for accepted proposals, after a quorum of members have voted to approve it, so are permitted to make modifications to the KV. Specifically, this context applies:
when evaluating the constitution’s
apply
function
Application context. These pieces of code execute endpoint handlers to implement the application logic, are invoked to handle incoming user requests, and may read and write from application tables.
Note
Since the constitution (and JS application) are written in JavaScript, there is also technically a global module evaluation context when the code is first ingested. It is expected that this only defines and exports the necessary functions. It has no access to the KV, and will result in errors if it attempts to access any KV table.
Restricted Permissions¶
CCF ensures that governance audit is possible offline from a ledger, by considering only a subset of transactions, and every governance change is traceable to member signatures. These governance transactions operate purely over governance tables, so that governance audit does not need to consider application tables, and purely over public tables so that all decisions can be reconstructed from the ledger. Combining the definitions above, we impose several restrictions on KV access in different contexts:
Governance code must never read from private tables. Doing so might make decisions which could not be reproduced from the ledger by an auditor (ie. without access to ledger secrets).
Governance code must never read from application tables. Doing so might produce dependencies on data which was not signed by a member.
Governance code running pre-approval must only have read access to tables, and never write.
Governance code should not write to application tables, which could be modified further outside of governance.
Application code must not modify governance tables, as it could do so without constitution approval.
Note
An important exemption here is that application code may still read from governance tables. This allows authentication, authorization, and metadata to be configured and controlled by governance, but affect the execution of application endpoints.
The possible access permissions are elaborated in the table below:
Table Category |
||||||
---|---|---|---|---|---|---|
Internal |
Governance |
Application |
||||
Execution context |
Public |
Private |
Public |
Private |
Public |
Private |
Pre-approval governance |
Read-only |
None |
Read-only |
None |
None |
None |
Post-approval governance |
Read-only |
None |
Writeable |
None |
None |
None |
Application |
Read-only |
None |
Read-only |
None |
Writeable |
Writeable |
Any violation of these restrictions (eg - calling set
on a Read-only table, or has
on a None table) results in an exception being thrown.