From 32f81ef892ed79c45c08e6bbebb30091a9783fac Mon Sep 17 00:00:00 2001
From: Tony Garnock-Jones <tonyg@leastfixedpoint.com>
Date: Thu, 13 Oct 2022 10:37:06 +0200
Subject: [PATCH] Gatekeeper and SturdyRef

---
 src/operation/builtin/gatekeeper.md   |  2 +-
 src/protocols/syndicate/gatekeeper.md | 60 +++++++++++++++++++++++++++
 2 files changed, 61 insertions(+), 1 deletion(-)

diff --git a/src/operation/builtin/gatekeeper.md b/src/operation/builtin/gatekeeper.md
index f697dca..775f9dc 100644
--- a/src/operation/builtin/gatekeeper.md
+++ b/src/operation/builtin/gatekeeper.md
@@ -36,7 +36,7 @@ current sturdyref implementation is based on the design of
 
 The following definitions are taken from the
 [sturdy.prs](https://git.syndicate-lang.org/syndicate-lang/syndicate-protocols/src/branch/main/schemas/sturdy.prs)
-schema.
+schema. For further detail, see the [reference](../../protocols/syndicate/gatekeeper.md).
 
 ```preserves-schema
 SturdyRef = <ref @oid any @caveatChain [Attenuation ...] @sig bytes>.
diff --git a/src/protocols/syndicate/gatekeeper.md b/src/protocols/syndicate/gatekeeper.md
index 3cb5cd5..3663004 100644
--- a/src/protocols/syndicate/gatekeeper.md
+++ b/src/protocols/syndicate/gatekeeper.md
@@ -1 +1,61 @@
 # Gatekeeper and Sturdy-references
+
+ - [`[syndicate-protocols]/schemas/gatekeeper.prs`](https://git.syndicate-lang.org/syndicate-lang/syndicate-protocols/src/branch/main/schemas/gatekeeper.prs)
+ - [`[syndicate-protocols]/schemas/sturdy.prs`](https://git.syndicate-lang.org/syndicate-lang/syndicate-protocols/src/branch/main/schemas/sturdy.prs)
+
+## Gatekeeper protocol
+
+The Gatekeeper protocol allows a peer to "upgrade" a `SturdyRef` to a live reference to an
+entity. For details of the use of `Resolve` and `Bind` assertions, see the [guide to the
+built-in gatekeeper entity](../../operation/builtin/gatekeeper.md).
+
+**Implementation.** The protocol is implemented within the
+[`syndicate-server`](../../operation/system-bus.md) program.
+
+```
+Resolve = <resolve @sturdyref sturdy.SturdyRef @observer #!#!any>.
+Bind = <bind @oid any @key bytes @target #!any>.
+```
+
+## Sturdy-reference structures
+
+A "sturdyref" is a long-lived certificate including a cryptographic signature that can be
+upgraded by a gatekeeper entity to a live reference to the entity named in the sturdyref. For
+an overview of `SturdyRef`s, see the [guide to the built-in gatekeeper
+entity](../../operation/builtin/gatekeeper.md#sturdyrefs).
+
+```
+SturdyRef = <ref @oid any @caveatChain [Attenuation ...] @sig bytes>.
+```
+
+For detail of the interpretation of `Attenuation`s, `Caveat`s, `Pattern`s, and `Template`s, see
+the [Syndicate protocol specification](../../protocol.md#capabilities-on-the-wire).
+
+```
+Attenuation = [Caveat ...].
+Caveat = Rewrite / Alts .
+Rewrite = <rewrite @pattern Pattern @template Template>.
+Alts = <or @alternatives [Rewrite ...]>.
+
+Lit = <lit @value any>.
+
+Pattern = PDiscard / PAtom / PEmbedded / PBind / PAnd / PNot / Lit / PCompound .
+PDiscard = <_>.
+PAtom = =Boolean / =Float / =Double / =SignedInteger / =String / =ByteString / =Symbol .
+PEmbedded = =Embedded .
+PBind = <bind @pattern Pattern>.
+PAnd = <and @patterns [Pattern ...]>.
+PNot = <not @pattern Pattern>.
+PCompound =
+    / @rec <rec @label any @fields [Pattern ...]>
+    / @arr <arr @items [Pattern ...]>
+    / @dict <dict @entries { any: Pattern ...:... }> .
+
+Template = TAttenuate / TRef / Lit / TCompound .
+TAttenuate = <attenuate @template Template @attenuation Attenuation>.
+TRef = <ref @binding int>.
+TCompound =
+    / @rec <rec @label any @fields [Template ...]>
+    / @arr <arr @items [Template ...]>
+    / @dict <dict @entries { any: Template ...:... }> .
+```