Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -676,7 +676,7 @@ A consent link lets the owner of an account connect it themselves: "tap here to
- A change to `consent` needs a restart; `SIGHUP` refuses it.

API:
- `POST /links` `{"service": "gmail", "ttl_seconds": 900, "label": "Alice"}` returns `{"url", "expires_at"}` (201). `ttl_seconds` is 60 to 3600 (default 900); the label (at most 100 characters) is shown on the page. Scopes, paths and keys cannot be set here: they come from the access file. Only `bearer`, `header` and `query` services, and `oauth2` services with an `auth_url`, can get a link; signing keys stay with the owner.
- `POST /links` `{"service": "gmail", "ttl_seconds": 900, "label": "Alice"}` returns `{"url", "expires_at"}` (201). `ttl_seconds` is 60 to 3600 (default 900); the label (at most 100 characters) is shown on the page. An optional `return_url` (https, at most 512 characters, on one of the consent block's `return_origins`, e.g. `"return_origins": ["https://app.example.com"]`) makes the done page say "Taking you back…" and go there after 3 seconds, with a button to go at once; without it the page says the person can close it. Scopes, paths and keys cannot be set here: they come from the access file. Only `bearer`, `header` and `query` services, and `oauth2` services with an `auth_url`, can get a link; signing keys stay with the owner.
- `DELETE /keys/<service>` deletes the service's stored key. For an `oauth2` service with a `revoke_url`, the provider is asked to revoke the refresh token first (RFC 7009); the key is deleted even if that fails, and the reply says `"revoked": false`.

The link:
Expand Down
1 change: 1 addition & 0 deletions deploy/cloudflare/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -72,6 +72,7 @@ Inputs:
|---|---|---|
| `PUBLIC_BASE` | var in `wrangler.jsonc` | https origin of the Worker, e.g. `https://keyring.example.com`; may change, see [Changing `PUBLIC_BASE`](#changing-public_base) |
| `SERVICES_TEMPLATE` | var in `wrangler.jsonc` | services each keyring starts with, and the router role's access |
| `RETURN_ORIGINS` | var in `wrangler.jsonc` (optional) | comma-separated https origins, e.g. `https://app.example.com`, that a link's `return_url` may point to; sent as consent `return_origins` on each keyring's next start, like a `PUBLIC_BASE` change |
| `MASTER_KEY` | secret | `head -c32 /dev/urandom \| base64`. Losing it makes every keyring unreadable; rotating it needs a re-seal (not built yet) |
| `CALLER_SECRET` | secret | the router's `X-Keyring-Caller` value, one per Phobos server |
| `ADMIN_TOKEN` | secret | the router's admin bearer token |
Expand Down
40 changes: 31 additions & 9 deletions deploy/cloudflare/src/index.ts
Original file line number Diff line number Diff line change
Expand Up @@ -23,6 +23,12 @@ export interface Env {
PUBLIC_BASE: string;
/** The services every new instance starts with (a JSON var). */
SERVICES_TEMPLATE: Template | string;
/**
* Optional, comma-separated https origins a connection link may send the
* person back to once connected (the link's return_url), e.g.
* https://app.example.com. Each keyring gets them on its next start.
*/
RETURN_ORIGINS?: string;
/** Secret: base64 of 32 random bytes; derives every instance's data key. */
MASTER_KEY: string;
/** Secret: the router's proof, sent as X-Keyring-Caller. */
Expand Down Expand Up @@ -268,13 +274,25 @@ const K_USAGE = "usage";
const K_OPEN_UNTIL = "openUntil";
const K_SECRETS = "clientSecretsHash";
const K_LAST_USED = "lastUsed";
/** The consent public_url last sent to the keyring and saved in its sealed state. */
const K_CONSENT_URL = "consentPublicUrl";
/**
* What of the consent settings was last sent to the keyring and saved in its
* sealed state (consentStamp; before return origins, the bare public_url).
*/
const K_CONSENT = "consentPublicUrl";
/** lastUsed is written to storage at most this often. */
const LAST_USED_WRITE_MS = 30 * 1000;

class Deleted extends Error {}

/**
* The part of the consent settings that can change between starts. Without
* return origins it is the bare public_url, the value kept before them, so
* existing keyrings are not sent the same settings again.
*/
function consentStamp(c: { public_url: string; return_origins?: string[] }): string {
return c.return_origins ? JSON.stringify([c.public_url, c.return_origins]) : c.public_url;
}

export class KeyringInstance extends DurableObject<Env> {

/** The one start in progress or done; null when the container is stopped. */
Expand Down Expand Up @@ -435,26 +453,30 @@ export class KeyringInstance extends DurableObject<Env> {

/** The keyring's consent settings; public_url follows PUBLIC_BASE. */
private async consentSettings(m: Identity) {
const origins = (this.env.RETURN_ORIGINS ?? "").split(",").map((o) => o.trim()).filter(Boolean);
return {
listen: `0.0.0.0:${PORT_PAGES}`,
public_url: `${this.env.PUBLIC_BASE}/connect`,
api_listen: `0.0.0.0:${PORT_CONSENT_API}`,
api_token_sha256: await sha256Hex(m.consentToken),
// Left out when empty, as the keyring omits it.
...(origins.length ? { return_origins: origins } : {}),
};
}

/**
* Sends the consent settings again when PUBLIC_BASE changed since they
* were last sent. The keyring builds link, Google page and callback URLs
* from its own public_url, kept in its sealed state; publishLink and the
* page route expect them under PUBLIC_BASE. Open links and accounts stay.
* Sends the consent settings again when PUBLIC_BASE or RETURN_ORIGINS
* changed since they were last sent. The keyring builds link, Google page
* and callback URLs from its own public_url, kept in its sealed state;
* publishLink and the page route expect them under PUBLIC_BASE. Open
* links and accounts stay.
*/
private async pushConsent(m: Identity): Promise<void> {
const consent = await this.consentSettings(m);
if (consent.public_url === (await this.ctx.storage.get<string>(K_CONSENT_URL))) return;
if (consentStamp(consent) === (await this.ctx.storage.get<string>(K_CONSENT))) return;
await this.adminJSON(m, "PUT", "/consent", consent);
await this.sync(m);
await this.put(K_CONSENT_URL, consent.public_url);
await this.put(K_CONSENT, consentStamp(consent));
}

private async pushClientSecrets(m: Identity): Promise<void> {
Expand Down Expand Up @@ -508,7 +530,7 @@ export class KeyringInstance extends DurableObject<Env> {
}
await this.pushClientSecrets(m);
await this.sync(m);
await this.put(K_CONSENT_URL, consent.public_url);
await this.put(K_CONSENT, consentStamp(consent));
if (!role.token) throw new KeyringError(502, "the keyring returned no role token");
return { role_token: role.token };
} catch (e) {
Expand Down
3 changes: 3 additions & 0 deletions deploy/cloudflare/wrangler.jsonc
Original file line number Diff line number Diff line change
Expand Up @@ -20,6 +20,9 @@
"vars": {
// Set to the Worker's https origin, e.g. https://keyring.example.com
"PUBLIC_BASE": "https://keyring.example.com",
// Optional, comma-separated https origins a link's return_url may point
// to: the done page sends the person back there after a few seconds.
"RETURN_ORIGINS": "",
// The services every new keyring starts with, and the router's access.
"SERVICES_TEMPLATE": {
"services": {
Expand Down
44 changes: 39 additions & 5 deletions internal/consent/consent.go
Original file line number Diff line number Diff line change
Expand Up @@ -86,6 +86,9 @@ type link struct {
google bool
googleEpoch uint64
workspace *workspace.ConsentBinding
// returnURL, if set, is where the done page sends the person back
// (an allowed return origin, checked when the link was made).
returnURL string
}

type signIn struct {
Expand All @@ -101,6 +104,7 @@ type signIn struct {
google bool
googleEpoch uint64
workspace *workspace.ConsentBinding
returnURL string // the link's
}

// New builds a consent server. config returns the settings in use (the
Expand Down Expand Up @@ -318,6 +322,9 @@ func (s *Server) createLink(w http.ResponseWriter, r *http.Request) {
Service string `json:"service"`
TTLSeconds int `json:"ttl_seconds"`
Label string `json:"label"`
// ReturnURL, optional, is where the person goes back after
// connecting: https on one of consent.return_origins.
ReturnURL string `json:"return_url"`
}
dec := json.NewDecoder(http.MaxBytesReader(w, r.Body, 4<<10))
dec.DisallowUnknownFields()
Expand Down Expand Up @@ -368,6 +375,13 @@ func (s *Server) createLink(w http.ResponseWriter, r *http.Request) {
apiError(w, http.StatusBadRequest, "label must be at most 100 characters without control characters")
return
}
if req.ReturnURL != "" {
u, err := url.Parse(req.ReturnURL)
if err != nil || len(req.ReturnURL) > maxReturnURL || !cfg.Consent.ReturnAllowed(u) || strings.ContainsAny(req.ReturnURL, " \t\r\n;") {
apiError(w, http.StatusBadRequest, "return_url must be an https URL on one of consent return_origins")
return
}
}
id := randomToken()
h := hashOf(id)
now := s.now()
Expand Down Expand Up @@ -396,7 +410,7 @@ func (s *Server) createLink(w http.ResponseWriter, r *http.Request) {
}
}
}
s.links[h] = &link{service: req.Service, key: svc.Key, extraHeaders: maps.Clone(svc.ExtraHeaders), label: req.Label, expires: expires, workspace: binding}
s.links[h] = &link{service: req.Service, key: svc.Key, extraHeaders: maps.Clone(svc.ExtraHeaders), label: req.Label, expires: expires, workspace: binding, returnURL: req.ReturnURL}
if svc.Auth == policy.AuthGcloudLogin {
s.links[h].google = true
s.links[h].googleEpoch = s.google.Epoch()
Expand Down Expand Up @@ -675,7 +689,7 @@ func (s *Server) linkSubmit(w http.ResponseWriter, r *http.Request, id string, p
s.startGoogle(w, r, l, h, public)
return
}
service, label := l.service, l.label
service, label, back := l.service, l.label, l.returnURL
if svc.Auth != policy.AuthOAuth2 {
var value string
var err error
Expand Down Expand Up @@ -715,7 +729,7 @@ func (s *Server) linkSubmit(w http.ResponseWriter, r *http.Request, id string, p
return
}
s.writeAudit("connected", map[string]any{"service": service, "key": svc.Key, "link": ref(h), "kind": "value"})
render(w, http.StatusOK, pageData{Service: service, Label: label, Message: "Saved. You can close this page."})
render(w, http.StatusOK, done(pageData{Service: service, Label: label}, "Saved.", back))
return
}
if len(s.signIns) >= maxPending {
Expand All @@ -736,6 +750,7 @@ func (s *Server) linkSubmit(w http.ResponseWriter, r *http.Request, id string, p
browser: hashOf(browser),
expires: now.Add(signInTTL),
workspace: l.workspace,
returnURL: back,
}
s.mu.Unlock()

Expand Down Expand Up @@ -876,7 +891,23 @@ func (s *Server) callback(w http.ResponseWriter, r *http.Request, public *url.UR
return
}
s.writeAudit("connected", map[string]any{"service": f.service, "key": svc.Key, "kind": "oauth2"})
render(w, http.StatusOK, pageData{Service: f.service, Message: "Connected. You can close this page."})
render(w, http.StatusOK, done(pageData{Service: f.service}, "Connected.", f.returnURL))
}

// maxReturnURL bounds a link's return_url.
const maxReturnURL = 512

// done is a success page: with a return URL it says it goes back and does
// so after a few seconds (a plain refresh: the pages run no scripts), with
// a button for doing it at once; without one, the person closes the page.
func done(data pageData, said, back string) pageData {
if back == "" {
data.Message = said + " You can close this page."
return data
}
data.Message = said + " Taking you back…"
data.Return = back
return data
}

// exchange trades the authorization code for tokens (RFC 6749 4.1.3, RFC
Expand Down Expand Up @@ -1002,6 +1033,8 @@ type pageData struct {
// GoogleStep is the Google connection's current step while it runs
// (1 sign-in, 2 project setup), shown as a list; 0 shows none.
GoogleStep int
// Return, on a success page, is where it sends the person back.
Return string
}

type credentialField struct {
Expand All @@ -1026,7 +1059,7 @@ func credentialForm(data *pageData, svc policy.Service) {
var page = template.Must(template.New("page").Parse(`<!doctype html>
<html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1">
<meta name="robots" content="noindex">
{{if .Refresh}}<meta http-equiv="refresh" content="2">{{end}}
{{if .Refresh}}<meta http-equiv="refresh" content="2">{{else if .Return}}<meta http-equiv="refresh" content="3;url={{.Return}}">{{end}}
<title>{{if .Label}}Connect {{.Label}}{{else if .Service}}Connect {{.Service}}{{else}}Private connection page{{end}}</title>
<style>
:root{--bg:#f7f8fa;--card:#fff;--ink:#16181d;--mut:#5f6670;--line:#e6e9ee;--blue:#2466e0;--green:#1f7d5a;--red:#b42318;--font:-apple-system,BlinkMacSystemFont,"Segoe UI",Inter,"Helvetica Neue",Arial,sans-serif}
Expand Down Expand Up @@ -1072,6 +1105,7 @@ input:focus,select:focus{border-color:var(--blue);box-shadow:0 0 0 3px rgba(36,1
{{if .Label}}<h1>Connect {{.Label}}</h1>{{else if .Service}}<h1>Connect {{.Service}}</h1>{{end}}
{{if .Message}}<div class="msg{{if or .Problem (ge .Status 400)}} err{{else if not (or .Form .Refresh)}} ok{{end}}{{if not (or .Label .Service)}} only{{end}}" role="{{if or .Problem (ge .Status 400)}}alert{{else}}status{{end}}">
{{if or .Problem (ge .Status 400)}}<svg width="20" height="20" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" aria-hidden="true"><circle cx="12" cy="12" r="9.5"/><path d="M12 7.5v5.5M12 16.5v.01"/></svg>{{else if not (or .Form .Refresh)}}<svg width="20" height="20" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><circle cx="12" cy="12" r="9.5"/><path d="m7.5 12.5 3 3 6-6.5"/></svg>{{else if .Refresh}}<span class="spin" aria-hidden="true"></span>{{end}}<span>{{.Message}}</span></div>{{end}}
{{with .Return}}<a class="btn" href="{{.}}">Back now</a>{{end}}
{{if .GoogleStep}}<ol class="steps" aria-label="Progress"><li class="{{if eq .GoogleStep 1}}now{{else}}done{{end}}">Sign in to Google</li><li{{if eq .GoogleStep 2}} class="now"{{end}}>Set up Drive and Sheets</li><li>Done</li></ol>{{end}}
{{if .Google}}
{{if .SignIn}}<p class="hint">Connect your own Google Drive and Sheets. After sign-in, this creates a Google Cloud project in your account and enables their APIs. No billing account is attached. Your Google credentials stay in your private keyring, not with the assistant.</p>{{end}}
Expand Down
49 changes: 46 additions & 3 deletions internal/consent/consent_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -192,9 +192,15 @@ func (e *env) api(method, path, token, body string) *httptest.ResponseRecorder {
}

// link creates a link and returns its path below the pages listener.
func (e *env) link(service string) string {
func (e *env) link(service string) string { return e.linkWith(service, "") }

// linkWith adds extra, `"field":value` pairs, to the create-link body.
func (e *env) linkWith(service, extra string) string {
e.t.Helper()
w := e.api("POST", "/links", apiToken, `{"service":"`+service+`","label":"Alice (+31 6...)"}`)
if extra != "" {
extra = "," + extra
}
w := e.api("POST", "/links", apiToken, `{"service":"`+service+`","label":"Alice (+31 6...)"`+extra+`}`)
if w.Code != http.StatusCreated {
e.t.Fatalf("create link for %s: %d %s", service, w.Code, w.Body)
}
Expand Down Expand Up @@ -406,7 +412,11 @@ func TestPagesListenerServesNothingElse(t *testing.T) {
// redirect and the cookie set on the browser.
func (e *env) startSignIn() (*url.URL, *http.Cookie) {
e.t.Helper()
path := e.link("gmail")
return e.signInFrom(e.link("gmail"))
}

func (e *env) signInFrom(path string) (*url.URL, *http.Cookie) {
e.t.Helper()
if w := e.page("GET", path, nil, nil); w.Code != http.StatusOK || !strings.Contains(w.Body.String(), "Sign in") {
e.t.Fatalf("gmail link page: %d %s", w.Code, w.Body)
}
Expand Down Expand Up @@ -884,3 +894,36 @@ func TestOAuthCallbackRechecksBindingAfterExchange(t *testing.T) {
t.Fatalf("callback published into a changed binding: %d", w.Code)
}
}

// A link made with a return_url sends the person back there once connected;
// one without keeps the close-this-page ending. Only allowed origins.
func TestReturnURLAfterConnecting(t *testing.T) {
e := newEnv(t)
e.cfg.Consent.ReturnOrigins = []string{"https://app.example.com"}
if err := e.cfg.Validate(); err != nil {
t.Fatal(err)
}
for _, bad := range []string{"https://evil.example.com/", "http://app.example.com/", "https://x@app.example.com/", "javascript:alert(1)", "https://app.example.com/;url=https://evil.example.com"} {
if w := e.api("POST", "/links", apiToken, `{"service":"gmail","return_url":"`+bad+`"}`); w.Code != http.StatusBadRequest {
t.Errorf("return_url %q: %d", bad, w.Code)
}
}
back := "https://app.example.com/g/7?tab=email"
to, cookie := e.signInFrom(e.linkWith("gmail", `"return_url":"`+back+`"`))
w := e.page("GET", callbackPath(url.Values{"code": {"good-code"}, "state": {to.Query().Get("state")}}), nil, nil, cookie)
body := w.Body.String()
if w.Code != http.StatusOK || !strings.Contains(body, "Taking you back") || strings.Contains(body, "close this page") ||
!strings.Contains(body, `<meta http-equiv="refresh" content="3;url=https://app.example.com/g/7?tab=email">`) ||
!strings.Contains(body, `href="https://app.example.com/g/7?tab=email"`) {
t.Fatalf("callback page: %d %s", w.Code, body)
}
// A value link also goes back; a plain one does not.
w = e.page("POST", e.linkWith("other", `"return_url":"https://app.example.com/"`), url.Values{"value": {"v"}}, fromPage)
if w.Code != http.StatusOK || !strings.Contains(w.Body.String(), `content="3;url=https://app.example.com/"`) {
t.Fatalf("value page: %d %s", w.Code, w.Body)
}
w = e.page("POST", e.link("other"), url.Values{"value": {"v"}}, fromPage)
if w.Code != http.StatusOK || strings.Contains(w.Body.String(), "url=") || !strings.Contains(w.Body.String(), "close this page") {
t.Fatalf("plain value page: %d %s", w.Code, w.Body)
}
}
4 changes: 2 additions & 2 deletions internal/consent/google.go
Original file line number Diff line number Diff line change
Expand Up @@ -38,7 +38,7 @@ func (s *Server) startGoogle(w http.ResponseWriter, r *http.Request, l *link, h
delete(s.links, h)
s.signIns[hashOf(state)] = &signIn{
service: l.service, browser: hashOf(browser), expires: s.now().Add(signInTTL),
google: true, googleEpoch: l.googleEpoch,
google: true, googleEpoch: l.googleEpoch, returnURL: l.returnURL,
}
s.mu.Unlock()
http.SetCookie(w, &http.Cookie{
Expand Down Expand Up @@ -115,7 +115,7 @@ func (s *Server) googlePage(w http.ResponseWriter, r *http.Request, id string, p
data.Form, data.GoogleCode = true, true
data.Message = "Open Google sign-in, then paste its verification code here. Never send the code in chat."
case "connected":
data.Message = "Drive and Sheets are connected. You can close this page."
data = done(data, "Drive and Sheets are connected.", f.returnURL)
case "failed":
data.Problem = true
data.Form, data.GoogleRetry = true, true
Expand Down
21 changes: 20 additions & 1 deletion internal/policy/policy.go
Original file line number Diff line number Diff line change
Expand Up @@ -115,6 +115,9 @@ type Consent struct {
APIAllowSources []string `json:"api_allow_sources"`
// APITokenSHA256 is the hex SHA-256 of the API token (keyring new-token).
APITokenSHA256 string `json:"api_token_sha256"`
// ReturnOrigins are the https origins a link may send the person back
// to after connecting (return_url); none = no link carries one.
ReturnOrigins []string `json:"return_origins,omitempty"`

public *url.URL
apiSources []netip.Prefix
Expand All @@ -127,7 +130,17 @@ func (a *Consent) Equal(b *Consent) bool {
return a == b
}
return a.Listen == b.Listen && a.PublicURL == b.PublicURL && a.APIListen == b.APIListen &&
slices.Equal(a.APIAllowSources, b.APIAllowSources) && a.APITokenSHA256 == b.APITokenSHA256
slices.Equal(a.APIAllowSources, b.APIAllowSources) && a.APITokenSHA256 == b.APITokenSHA256 &&
slices.Equal(a.ReturnOrigins, b.ReturnOrigins)
}

// ReturnAllowed reports whether link u, already parsed, may be a return
// URL: https, no user info, and its origin exactly one of ReturnOrigins.
func (a *Consent) ReturnAllowed(u *url.URL) bool {
if u == nil || u.Scheme != "https" || u.User != nil || u.Host == "" || u.Opaque != "" {
return false
}
return slices.Contains(a.ReturnOrigins, u.Scheme+"://"+u.Host)
}

// PublicBase returns the parsed public_url of validated settings.
Expand Down Expand Up @@ -997,6 +1010,12 @@ func (k *Consent) validate(c *Config, proxy netip.AddrPort) error {
if !tokenHash.MatchString(k.APITokenSHA256) {
return errors.New("consent api_token_sha256 must be 64 lowercase hex characters")
}
for _, o := range k.ReturnOrigins {
u, err := url.Parse(o)
if err != nil || u.Scheme != "https" || u.Host == "" || u.User != nil || u.Path != "" || u.RawQuery != "" || u.Fragment != "" || u.Opaque != "" || u.Scheme+"://"+u.Host != o {
return fmt.Errorf("consent return_origins: %q must be an https origin such as https://app.example.com", o)
}
}
return nil
}

Expand Down
Loading
Loading