Status ~2024.10.29. %emissary works for most applications but has occasional connectivity bugs via remote scry that have proven difficult to diagnose.
%emissary allows a running star to designate a planet as its representative. (This is tied to operation not merely to ownership.) The app is served at /app/emissary.
%emissary allows app developers to permit delegate planets to exercise star-related powers and privileges. It can be used for arrangements beyond this, however.
There are three roles one can play with respect to %emissary:
- Patron. A point (typically a point on a tier heavier in the address space, such as a galaxy or star) will designate a delegate (commonly a star or planet). A patron exposes a public attestation of the delegation to remote scry.
- Delegate. A point (typically a point lighter in the address space, such as a star or planet) will act as a delegae of a patron (commonly a galaxy or star). A delegate exposes a public attestaion of the delegation to remote scry.
- Observer. A third-party app or point wishes to verify whether two points are in a patronage relationship. This observer must periodically remote scry both points for agreement.
Special thanks to ~paldev for /lib/rudder and to ~midden-fabler for %ahoy (code from which was coopted here for breach detection).
%emissary is available under the MIT License.
Install over the wire from ~magbel.
|install ~magbel %emissaryInstall from source by cloning this repository then copying the contents of the desk/ directory into your ship as usual.
git clone https://github.com/sigilante/emissary.git
yes | cp -r emissary/desk/* zod/emissaryThe patron is responsible to send a request to another point for that point to act as its delegate.
Delegation may be managed through the patron portal online or using CLI generators:
:emissary|designate ~sampel-palnet
:emissary|revoke ~sampel-palnetServed at /app/emissary/patron.
The delegate-designee may review and either accept or reject requests from other points to serve as their delegate.
Delegation may be managed through the delegate portal online or using CLI generators:
:emissary|accept ~sampel
:emissary|reject ~sampelServed at /app/emissary/delegate.
An observer may query whether a point has any delegates or any patrons.
Served at /app/emissary/observer.
:: Get set of all confirmed delegates.
.^((set @p) %gy /=emissary=/delegates)
:: Get set of all pending outgoing requests.
.^((set @p) %gy /=emissary=/outgoing)
:: Get set of all pending incoming requests.
.^((set @p) %gy /=emissary=/incoming)
:: Get set of all confirmed patrons.
.^((set @p) %gy /=emissary=/patrons)
:: Check status of single delegate claim.
.^(? %gx /=emissary=/delegate/~sampel-palnet/emissary-demand)
:: Check status of single patron claim.
.^(? %gx /=emissary=/patron/~sampel-palnet/emissary-demand)The following scry endpoints are bound (with appropriate revision number and the same types as above):
:: Get set of all confirmed delegates.
/g/x/0/emissary//delegates
:: Get set of all pending outgoing requests.
/g/x/0/emissary//outgoing
:: Get set of all pending incoming requests.
/g/x/0/emissary//incoming
:: Get set of all confirmed patrons.
/g/x/0/emissary//patrons
:: Check status of single delegate claim.
/g/x/0/emissary//delegate/~sampel-palnet
:: Check status of single patron claim.
/g/x/0/emissary//patron/~sampel-palnetYou can request one of these values at the current time using a
%keen task (without the double //):
[%pass /emissary/fine %arvo %a %keen ~sampel-palnet /g/x/0/emissary/delegate/~sampel]If the target ship has participated in %emissary, then that task
will trigger the return of a %tune gift of the form:
[%tune [~sampel-palnet /emissary/fine] `roar]The +$roar will contain the remote scry path and the value in
its head. (The tail is the signature.) That head:
[/g/x/0/emissary/delegate/~sampel [~ %.y]]You can (locally) check currently bound scry paths thus:
> .^(* %gx /=emissary=//patron/~zod)
0
> ;;([%patron ?] .^(* %gx /=emissary=//patron/~zod))
[%patron %.n]
> .^((set @p) %gy /=emissary=/incoming)
{~zod}
> .^((list path) %gt /=emissary=//patron)
~[/patron/~zod]
> .^([%ud @ud] %gw /=emissary=//patrons)
[%ud 11]A third-party agent should be careful to use the latest revision of the delegation. It remains to decide what is a good interval for this attestation to remain valid (i.e. if a star is taken offline). We also need to produce a library core to facilitate checking both points easily.
The major data structures include:
+$ triggerfor a patron to decide about a delegate.+$ requestfor a parton to send to a delegate.+$ decidefor a delegate to decide about a patron.+$ responsefor a delegate to reply to a patron.+$ demandrepresents responses to scries (local and remote).
Canonically, trigger → request → decide → response.
You may use the /mar/emissary/demand file to properly process
a response to a marked scry.
+acceptfor a delegate to accept a patron.+designatefor a patron to request a delegate.+rejectfor a delegate to refuse a patron.+revokefor a patron to unrequest a delegate.
%emissary uses /lib/rudder to present its browser interface.
[1 0 0]initial release, local scry only[1 1 0]add support for remote scry; reorganize actions; adjust scry paths; add observer page[1 1 1]adjust CSS[1 2 0]hotfix remote scry on livenet; rework query data structure[1 3 0]tombstone stale remote scry endpoints[1 4 0]remove patrons and delegates on breach notification[1 4 1]bump to 411 K; modify remote scry task signatures[1 4 2]modify remote scries for 411K
- add observer library
- add QR code status check