diff --git a/README.md b/README.md index 1c9c4df..17289ed 100644 --- a/README.md +++ b/README.md @@ -7,7 +7,9 @@ These documents define abstract wire and protocol semantics — types, encodings * [Core primitives](core-definitions/README.md) * [Alias](core-definitions/alias.md) * [App](core-definitions/app.md) + * [Bundle](core-definitions/bundle.md) * [Channel](core-definitions/channel.md) + * [Contract](core-definitions/contract.md) * [Exonet](core-definitions/exonet.md) * [Identity](core-definitions/identity.md) * [Link](core-definitions/link.md) @@ -18,6 +20,7 @@ These documents define abstract wire and protocol semantics — types, encodings * [Object Stream](core-definitions/object-stream.md) * [Object Type](core-definitions/object-type.md) * [Op (Operation)](core-definitions/op.md) + * [Permit](core-definitions/permit.md) * [Protocol](core-definitions/protocol.md) * [Query](core-definitions/query.md) * [Query String](core-definitions/query-string.md) @@ -25,6 +28,7 @@ These documents define abstract wire and protocol semantics — types, encodings * [Structure](core-definitions/structure.md) * [Swarm](core-definitions/swarm.md) * [User](core-definitions/user.md) + * [Zone](core-definitions/zone.md) * [Common types](primitive-types/README.md) – common object types * [ack](primitive-types/ack.md) * [bool](primitive-types/bool.md) diff --git a/core-definitions/bundle.md b/core-definitions/bundle.md new file mode 100644 index 0000000..fe9cf24 --- /dev/null +++ b/core-definitions/bundle.md @@ -0,0 +1,8 @@ +# Bundle + +* A `Bundle` is an ordered collection of unique [`Objects`](object.md) of various types. +* A `Bundle` is itself an [`Object`](object.md); its [`Object Type`](object-type.md) is `bundle`. +* An `Object` appears at most once in a `Bundle`. +* A `Bundle` preserves the order in which `Objects` were added. +* `Bundles` are used wherever a single `Object` must carry a set of others — for + example, the constraints of a [`Permit`](permit.md). diff --git a/core-definitions/contract.md b/core-definitions/contract.md new file mode 100644 index 0000000..006b0c4 --- /dev/null +++ b/core-definitions/contract.md @@ -0,0 +1,14 @@ +# Contract + +* A `Contract` is a permission granted by one [`Identity`](identity.md) (the `Issuer`) to + another (the `Subject`), authorising the `Subject` to represent the `Issuer` on the + `Astral Network` in some capacity. +* A [`User`](user.md) signs a `Contract` with a [`Node`](node.md) so the `Node` can act for the + `User`; an [`App`](app.md) signs a `Contract` with its host `Node` so the `Node` can route + its traffic. +* A `Contract` carries an `Issuer`, a `Subject`, a list of [`Permits`](permit.md), and an + expiry time. +* A `Contract` grants an action when one of its `Permits` matches that action. +* A `Contract` carries no signatures on its own; once co-signed by both the `Issuer` + and the `Subject` it becomes a `Signed Contract`. +* See the wire type [`mod.auth.contract`](../protocols/auth/types/mod.auth.contract.md). diff --git a/core-definitions/permit.md b/core-definitions/permit.md new file mode 100644 index 0000000..020e04b --- /dev/null +++ b/core-definitions/permit.md @@ -0,0 +1,10 @@ +# Permit + +* A `Permit` is a single capability granted by a [`Contract`](contract.md). +* A `Permit` names the [`Object Type`](object-type.md) of an action it authorises. +* A `Permit` may carry an optional [`Bundle`](bundle.md) of constraints that narrow the + grant. +* When the permitted action supports constraints, it evaluates the constraints to + decide whether the `Permit` applies; actions that do not are permitted + unconditionally. +* See the wire type [`mod.auth.permit`](../protocols/auth/types/mod.auth.permit.md). diff --git a/core-definitions/zone.md b/core-definitions/zone.md new file mode 100644 index 0000000..0030b20 --- /dev/null +++ b/core-definitions/zone.md @@ -0,0 +1,17 @@ +# Zone + +* A `Zone` scopes where a [`Query`](query.md) or [`Operation`](op.md) may be routed and + resolved. +* There are three `Zones`: + * `Device` — local to the [`Node`](node.md) itself: its own storage and hosted + [`Apps`](app.md). + * `Virtual` — the `Node`'s virtual providers, which are neither device-local nor + on the network. + * `Network` — other [`Nodes`](node.md), reached over [`Links`](link.md). +* A `Zone` is a set: any combination of the three can be permitted at once. +* An `Operation` that accepts a `Zone` treats it as a filter; the default is all + `Zones`. +* The `Network` `Zone` is stripped from untrusted queries (e.g. anonymous guests), + confining them to the local `Node`. +* A `Zone` is written in text as a string of `d`, `v`, `n` (e.g. `dvn`), and on the + wire as a [`uint8`](../primitive-types/uint8.md) bit field.