is_web_request_driver 0.4.0
is_web_request_driver: ^0.4.0 copied to clipboard
intersyntactic's web request driver: sends requests out of the home under the person's sign-ins, holding each sign-in's secret so no tool or record ever sees it.
is_web_request_driver #
intersyntactic's web request driver: the service that CarriesOutWebRequests (from
is_effects), making each
Request under one of the person's sign-ins. A tool describes the request
and names a sign-in such as cam-teams, and the airlock decides on it. The
web request driver holds the secret and is the only piece that ever sees it.
It knows nothing about any destination. A sign-in's kind is a way of proving who you are, such as OAuth 2 client credentials. Everything a destination adds sits in that sign-in's file: where its token comes from, which sites it's for, and which field of a reply names what was made. So Teams, Slack or GitHub is a file, not a change to this package.
What carrying out a web request does #
-
The path stays on its origin.
pathis appended toorigin, and the driver refuses anything that would name another site. For example,@evil.exampleafterhttps://a.examplereads as a login toevil.example. -
A sign-in goes only to its own sites. The airlock decides by name alone, so it can't know that a sign-in next to an origin outside its file would hand a token to a stranger. Only the driver can, and it refuses that web request.
-
The driver signs the request. It does this the way the sign-in's kind says, and keeps any token until five minutes before it expires. Concurrent web requests share a single fetch.
-
It reads what the destination made. That becomes
WebResponse.created: the field the sign-in names, taken from a 2xx JSON reply. -
It says why a destination refused. A failure moves a piece of information of its own: why. A
400's body names the problem, and a refused token's names the cause (AADSTS7000215is a wrong secret). The record keeps what it's given for good, so it gets a word, not the body.WebResponse.refusedBecauseis the one field the sign-in names as its reason, such aserror.code→ConversationNotFound. A refused token'sRefusedreason carries OAuth's ownerrorcode, such asinvalid_client. The whole body goes only to the driver's log, for whoever runs it. The service logs to stdout, which is the journal on the box, and bodies are clipped to 2,000 characters. A successful reply is never logged, and neither is a token service's 200, since that body is the token.
Ran(WebResponse) means the request left the home and got a reply, whatever its
status. Refused means nothing reached the destination: an unknown sign-in,
a foreign origin or path, a token the sign-in service wouldn't issue, or a
network failure before any reply.
Sign-ins #
Credential.load(directory) reads every file in directory, one per
sign-in, each named for its sign-in. That is the layout systemd's
LoadCredential= produces in $CREDENTIALS_DIRECTORY, where only the
service's user can read the files. The program that runs the driver passes
in that directory. This package never reads the environment.
| kind | signs with | fields |
|---|---|---|
client-credentials |
an OAuth 2 bearer token from tokenUrl (https only) |
tokenUrl, clientId, secret, optional scope |
Every kind also takes origins, the only sites the sign-in is ever shown
to, and two optional reply fields, each a path of keys such as error.code:
created, naming what a 2xx reply made, and refusedBecause, naming why a
non-2xx reply refused.
For example, cam-teams is a Teams bot. Its created is the new activity's
id, which a card press names later. Its refusedBecause is the Bot
Framework error's code:
{
"kind": "client-credentials",
"tokenUrl": "https://login.microsoftonline.com/<tenant>/oauth2/v2.0/token",
"clientId": "<app id>",
"secret": "<app secret>",
"scope": "https://api.botframework.com/.default",
"origins": ["https://smba.trafficmanager.net"],
"created": "id",
"refusedBecause": "error.code"
}
Running as its own service #
Each driver is a wall of its own (RULINGS). It runs as its own OS user, holds only its own secrets, and answers only the airlock's user. So the driver runs as a service:
WEB_REQUEST_DRIVER_SOCKET=/run/intersyntactic-web-driver/web-driver.sock \
WEB_REQUEST_DRIVER_CALLER=<the airlock's user> \
dart run is_web_request_driver:service # CREDENTIALS_DIRECTORY from LoadCredential=
The service reads who is calling from the socket, as the kernel reports it
(SO_PEERCRED), the same way is_journal's writer knows its senders. It
answers no one else: a connection from any other user is closed unanswered,
and no web request is made. A caller writes one request per connection and closes
its side. The service answers one line and closes. Both are is_effects' own JSON
(encodeRequest, encodeOutcome with encodeWebResponse), shared
with the airlock, so neither side keeps a codec of its own:
→ {"origin":"https://…","method":"post","path":"/…","signIn":"cam-teams","headers":{…},"body":"…"}
← {"kind":"ran","output":{"status":201,"created":"…","refusedBecause":null}}
← {"kind":"refused","why":"…"}
A web request that got a 4xx reply still ran. A path that would name
another site can't be built as a WebPath, and the socket refuses one
arriving as text before anything is made. The airlock side is WebRequestDriverSocket from
package:is_web_request_driver/service.dart. It CarriesOutWebRequests and holds no secret, so the airlock
holds it as it would any other way of carrying out web requests. Each
sign-in is its own file, so a sign-in that needs a wall of its own can run
as a second instance of this service with only that file.