8000 feat(circles): people on other servers in your circles, over ActivityPub by adeelahmad · Pull Request #667 · adeelahmad/lense · GitHub
[go: up one dir, main page]

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
8000
Diff view
Diff view
5 changes: 3 additions & 2 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -242,7 +242,9 @@ listed under [In progress](#in-progress), and what comes next under [Planned](#p
live under Profile and Share sits on every timeline item and resource. Rules (automations) share what comes in,
like the school's emails, asking you first until you let them run on their own. Let a circle see when you're free
(never what), and agents find a time that suits everyone, or ask your agent questions about the namespaces you
pick, answered with citations. Agents do the same over MCP, and the assistant asks you first before sharing.
pick, answered with citations. Once an admin turns it on, circles hold people on other Lens or ActivityPub servers
by handle, and shares reach them signed. Agents do the same over MCP, and the assistant asks you first before
sharing.
([Circles of trust](docs/circles.md);
[checks](docs/requirements.md#share-with-the-people-close-to-you))
- **See what it costs.** An activity ledger of every model call, with reports, charts and budgets that cap spending.
Expand Down Expand Up @@ -338,7 +340,6 @@ Open pull requests, not yet part of Lens, are listed here; none right now.

Next, and not in a pull request yet; each links to where it is tracked:

- **Circles of trust:** circles across Lens servers over ActivityPub ([circles of trust](docs/circles.md)).
- **Notes:** nesting a note under its project or area without a click, pages in the graph, and wiki addresses for
topics, recordings and the other things that have pages ([notes](docs/notes.md)).
- **Local models:** GPU builds of llama.cpp fetched by Lens, and local embedding models
Expand Down
6 changes: 6 additions & 0 deletions changelog.d/circles-elsewhere.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,6 @@
- **Circles with other servers.** Once an admin turns it on (Settings → Circles elsewhere) and you make yourself
findable under Profile, you get a handle like `adeel@lens.example`, and your circles can hold people on other Lens
or ActivityPub servers by theirs. What you share with those circles reaches them as a signed ActivityPub `Note`, and
what they send you lands in your timeline, taken only signed, recent and from someone in a circle. Through the API,
MCP `circles_elsewhere` and `save_circle`, and Profile → Circles
([Circles with other servers](docs/federation.md)).
8 changes: 7 additions & 1 deletion docs/api.md
Original file line number Diff line number Diff line change
Expand Up @@ -269,6 +269,9 @@ GET /api/v1/circles/shares
POST /api/v1/circles/shares
POST /api/v1/circles/when-free
POST /api/v1/circles/ask
GET /api/v1/circles/elsewhere
PUT /api/v1/circles/elsewhere
GET /api/v1/circles/shares/{share_id}/elsewhere
DELETE /api/v1/circles/shares/{share_id}
GET /api/v1/circles/{circle_id}
PATCH /api/v1/circles/{circle_id}
Expand All @@ -286,7 +289,10 @@ you're free. `POST /circles/when-free` takes `people`, a window (`start`, `end`,
`day_start` and `day_end`, and answers each person's busy times (only when, never what) or why not, and the free
stretches when you and all of them are free; each person asked gets `agent.asked` in their timeline. With `lets`
holding `questions` and `about` naming namespaces of yours, `POST /circles/ask` (`person`, `question`) answers from
those namespaces only, with its `sources`; the person asked sees the question and the answer.
those namespaces only, with its `sources`; the person asked sees the question and the answer. Once an admin turns on
[circles with other servers](federation.md), `PUT /circles/elsewhere` (`findable`) gives you a handle, circles take
people elsewhere by handle (`remote`, `add_remote`, `remove_remote`), and `GET /circles/shares/{id}/elsewhere` says
how a share is getting on with them.

## automations

Expand Down
2 changes: 1 addition & 1 deletion docs/automations.md
Original file line number Diff line number Diff line change
Expand Up @@ -217,7 +217,7 @@ and the paths holding outside text are in `GET /api/v1/activities/kinds` (`event
| `approval.waiting` | | `approvals` | `{type: Question, id: lens:approval/<id>, name: what it would do, url: /approvals?id=<id>}`, `status`, `action`, `effect`, `automation`, `automation_name`, `run`, `node`, `about` (the activity that caused it), `expires_at`; its person alone sees it | School emails asks for your pick: Post in the Matterbridge gateway family: “Trip on Friday, bring a packed lunch” |
| `approval.decided` | | `approval_decisions` | as `approval.waiting`, with `status` (done, failed, declined, expired) and `error`; `Accept` when approved, `Reject` when declined or expired | Sam approved: Post in the Matterbridge gateway family: “Trip on Friday, bring a packed lunch” |
| `share.sent` | | `shares_sent` | what was [shared with a circle](circles.md) as it read then (`type`, `id`, `name`, `url`, `summary`: the timeline's line, `media`, `kind` and `about`: the activity shared, `published`), `content` (the note), `share`, `circles`, `people`, `with_item`; tagged with its entities; the sharer alone sees it | Adeel shared “School trip on Friday” with Immediate family |
| `share.received` | | `shares_received` | as `share.sent`, without `circles` and `people`; `url` only when the person can open it; in no namespace; that person alone sees it | Adeel shared “School trip on Friday” with you |
| `share.received` | | `shares_received`, `shares_remote` | as `share.sent`, without `circles` and `people`; `url` only when the person can open it; in no namespace; that person alone sees it. From someone [on another server](federation.md) (`shares_remote`): a `Note` with `name`, `content` and `remote: true`, the actor's `handle`, all outside text | Adeel shared “School trip on Friday” with you |
| `agent.asked` | | `agent_asks` | what someone's agent asked of the person (`what`: `free_busy`, the window as `startTime` and `endTime`; or `question`, the question as `name` and the answer as `content`, both outside text); in no namespace; the person asked alone sees it | Sam's agent asked when you're free, Mon 20 Oct – Fri 24 Oct |

A new asset is one activity, of the most specific kind its row tells, decided by its content type and where it came
Expand Down
8 changes: 5 additions & 3 deletions docs/circles.md
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,7 @@ Status: in progress. Circles are built in steps; only what is merged is called b
| Rules: an automation shares what you pick (by kind, sender, entity or the decision model) with a circle, asking you first or on its own | built |
| When they're free: a circle can see when you're free (never what), and agents find a time that suits everyone | built |
| Asking someone's agent a question (what does the trip need), answered only from the namespaces they let that circle ask about, with citations | built |
| Circles across Lens servers over ActivityPub: a signed inbox, an outbox and WebFinger handles like `sam@lens.example` | planned |
| [Circles with other servers](federation.md) over ActivityPub: people elsewhere by handle (`sam@lens.example`), shares sent to them signed and theirs received, off until an admin turns it on | built |

## Circles

Expand All @@ -23,7 +23,9 @@ not even the people in them. The usual ones are offered as suggestions (Immediat
Colleagues); none is made for you.

You can add people you share a namespace with, and people who have you in a circle of theirs, so your son can add you
back once you have added him. Admins can add anyone. Adding someone tells them nothing; sharing does.
back once you have added him. Admins can add anyone. Adding someone tells them nothing; sharing does. Once an admin
turns it on, a circle can also hold people on other Lens or ActivityPub servers, by handle
([Circles with other servers](federation.md)).

**In the web app**, your circles are under Profile: a suggested name makes a circle in one click, *Add someone…*
adds a person, the × by a name takes them out, and deleting a circle is undone from its message.
Expand Down Expand Up @@ -104,7 +106,7 @@ Everything here works for agents as it does for people.
they're busy and when everyone is free; a circle's `lets` turns it on. `POST /api/v1/circles/ask` (`person`,
`question`) asks their agent; a circle's `lets: ["questions"]` and `about` (namespaces) let it.
- **MCP:** `list_circles` (with `shares`: received or sent), `save_circle`, `share_with_circle`, `undo_share`,
`when_free` and `ask_their_agent`. They are about the person, so a namespace's own MCP server doesn't offer them.
`when_free`, `ask_their_agent` and `circles_elsewhere`. They are about the person, so a namespace's own MCP server doesn't offer them.
- **The assistant:** `circles` reads them, `share_with_circle` asks the person first (telling other people is always
their pick), `when_free` finds a time, and `ask_their_agent` asks someone's agent.
- **Automations:** the `share_with_circle` action ([Rules](#rules)), which agents can add with the automation tools.
Expand Down
83 changes: 83 additions & 0 deletions docs/federation.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,83 @@
# Circles with other servers

Your family isn't always on the same Lens. Your partner may run their own, and your parents may use another
ActivityPub server. With circles across servers, you put them in a circle by their handle (`sam@lens.example`), and
what you share with that circle reaches them too, in their own timeline. What they send you lands in yours. It uses
ActivityPub, the open standard Mastodon and others speak, so nothing ties you to Lens.

Status: built. Sharing travels between servers; asking someone's agent and seeing when they're free work on the same
Lens only (see [Refine later](#refine-later)).

## Turning it on

It is off until an admin turns it on, in Settings → Security and access → Circles elsewhere:

| Setting | Default | What it does |
| --- | --- | --- |
| `federation.enabled` | `false` | let circles hold people on other servers, and answer WebFinger and `/ap` |
| `federation.url` | empty | this Lens's public `https://` address; empty means the [HTTPS](https.md) domain's |

Other servers must reach Lens over https:// at that address, so it needs [HTTPS](https.md) on your own domain, or a
[tunnel](remote-access.md) with a fixed hostname set as `federation.url`. Without one, nothing is turned on.

Even then, nobody can be found until they say so. Under Profile → Circles, *People on other servers can find you*
gives you a handle (your name or email's first part, `@` the Lens's domain) and a key pair to sign what you send.
Turning it off deletes both; servers that knew you can no longer reach you.

## People elsewhere in your circles

Under Profile → Circles, type someone's handle under a circle and press Enter. Lens looks them up the way Mastodon
does (WebFinger at their server, then their ActivityPub actor), checks that their actor and key are their own, and
keeps their name, inbox and public key. They show in the circle with a dashed border; the × takes them out.

Adding someone tells them nothing. For them to send you things, they add your handle to a circle of theirs.

## What travels

**What you share.** Sharing with a circle that holds people elsewhere (from the timeline, a resource, a rule or an
agent) sends each of them a `Create` of a `Note`: the share's name, your note and the line the timeline showed. The
item itself, its links into your Lens and anything in a vault never leave. Each is signed with your key
([HTTP Signatures](https://datatracker.ietf.org/doc/html/draft-cavage-http-signatures), `rsa-sha256` over
`(request-target)`, `host`, `date` and `digest`) and sent from a queue: tried again after 1, 5 and 30 minutes, then 2
and 12 hours, then given up with the reason. `GET /api/v1/circles/shares/{id}/elsewhere` says how each is getting on.
Undoing the share sends a `Delete` to everyone it reached.

**What they share with you.** A signed `Create` of a `Note` sent to your inbox shows in your timeline as
`share.received` from them, once, and their `Delete` (or `Undo`) takes it back. Lens takes it only when:

- the signature checks out against the key Lens kept when you added them (Lens never fetches a key an inbox request
points to), over the request target, host, date and a digest that matches the body;
- its date is within five minutes;
- the activity's actor is who signed it; and
- they are in one of your circles.

Its text is taken out of any HTML and marked as outside text (`lens.untrusted`), so agents read it as data, never as
instructions. Everything else sent to an inbox is accepted and dropped.

Nothing is public: your outbox is always empty, your actor says it isn't discoverable or indexable, and no model is
called.

## For agents

- **API:** `GET` and `PUT /api/v1/circles/elsewhere` (`findable`) read and set whether you're findable, with your
handle. `POST /api/v1/circles` takes `remote` (handles), `PATCH /api/v1/circles/{id}` takes `add_remote` and
`remove_remote`, and a share answers `elsewhere`: who it's being sent to. Audited as `circle.findable`.
- **MCP:** `circles_elsewhere` (read, or set `findable`) and `save_circle`'s `add_remote` and `remove_remote`.
- **ActivityPub:** `GET /.well-known/webfinger?resource=acct:<handle>`, `GET /ap/users/<name>` (the actor, with its
public key), `GET /ap/users/<name>/outbox` (empty) and `POST /ap/users/<name>/inbox`. They answer 404 while it is
off, and for anyone who isn't findable.

## What keeps it safe

- Off by default, and each person decides whether they can be found. Nobody is listed or discoverable.
- Lens fetches only `https://` addresses at public IP addresses (and the private networks an admin allowed in Settings
→ Documents), through the same guard web pages are captured with; an inbox request never makes Lens fetch anything.
- Private keys are sealed with the server's secret; removing an account deletes its keys, queue and what it received.
- See `threat-model.md` (federation entry point, P-FEDERATION).

## Refine later

- Asking someone's agent, and when they're free, between servers (`Question` activities).
- A person's key rotated on their server: fetch their actor again when a signature fails.
- Deliver a share to everyone on one server through its shared inbox.
- Shares from Mastodon and other servers that send `Announce` or a direct `Note` without `Create`.
3 changes: 2 additions & 1 deletion docs/mcp.md
Original file line number Diff line number Diff line change
Expand Up @@ -137,11 +137,12 @@ For an app that speaks OpenAI's API rather than MCP, the namespace can also answ
| `approvals` | what waits for your pick, newest first ([Approvals](automations.md#approvals)): an automation's actions and the assistant's proposals, each with what it would do, why, when it expires, its link and what an agent may do (`can`); one by `id`, by `status` (pending by default, or `any`), `origin`, `automation` or the `activity` that caused them, a page at a time. On a namespace's own server, that namespace's alone. What it would do holds text the automation read from outside Lens |
| `decline_approval` | decline one of your approvals by id: nothing is done, and the run records it. There is no tool to approve: that is your pick, in Lens or your chat app. Needs a write-scope token |
| `list_circles` | your [circles of trust](circles.md), each with its members, the people you can add, and with `shares` (received or sent) what was shared with you or by you, newest first |
| `save_circle` | make a circle (`name`, `members` by account id or email) or change one of yours (`circle_id`: rename, set `members`, `add`, `remove`, set `lets` (`free_busy` lets its people see when you're free, `questions` lets them ask your agent about the namespaces in `about`), or `delete`). Needs a write-scope token |
| `save_circle` | make a circle (`name`, `members` by account id or email) or change one of yours (`circle_id`: rename, set `members`, `add`, `remove`, set `lets` (`free_busy` lets its people see when you're free, `questions` lets them ask your agent about the namespaces in `about`), `add_remote` and `remove_remote` people on other servers by handle, or `delete`). Needs a write-scope token |
| `share_with_circle` | tell people in your circles about an activity (by id) or a resource you can see, with a `note`: each sees it in their own timeline; `with_item` also gives them permission on the resource (needs `publish` there). Nothing in a vault. Needs a write-scope token |
| `undo_share` | take a share back: it leaves everyone's timeline, and the permissions it gave are taken back. Needs a write-scope token |
| `when_free` | when people in your circles are busy in a window, for those who let you see it (only when, never what), and when you and all of them are free for at least `minutes` within the hours of the day, in a time zone: to find a time for a call or a trip. Each person asked sees it in their timeline |
| `ask_their_agent` | ask the agent of someone in your circles a `question`: it answers only from the namespaces they let you ask about, citing them, and they see the question and the answer in their timeline |
| `circles_elsewhere` | whether people on other servers can find you, and your handle; `findable` true or false changes it ([Circles with other servers](federation.md)). Changing it needs a write-scope token |
| `automations` | the person's automations ([Automations](automations.md#agents)): each one's triggers, whether it's on, its last run and what waits; with `automation_id` one in full with its latest runs, with `run_id` one run with its trace, log and what its actions did |
| `automation_actions` | what an automation's action nodes can do: each action's params, what it reaches and what it gives back |
| `save_automation` | make an automation, or change one: name, triggers, its If (`condition`), its graph, namespaces, limits; a new one is saved switched off unless `enabled` is true. Problems come back in plain words; a node never runs on its own from here. Needs a write-scope token |
Expand Down
1 change: 1 addition & 0 deletions docs/requirements.md
Original file line number Diff line number Diff line change
Expand Up @@ -293,6 +293,7 @@ request, to another check that proves the same thing; loosening a requirement or
| Share on a timeline item or a resource picks the only circle, takes a note and is undone from its toast | [circles-ui.test.tsx](https://github.com/adeelahmad/lense/blob/main/nextjs-frontend/__tests__/circles-ui.test.tsx) `picks the only circle, shares with a note, and undoes from the toast` |
| A rule shares what comes in with a circle and a note, asking first until the person lets it run on its own | [test_circles.py](https://github.com/adeelahmad/lense/blob/main/fastapi_backend/tests/api/test_circles.py) `test_rules_share_on_their_own_only_when_let` |
| A circle sees when you're free only once you let it, only when and never what, each ask in your timeline; agents and the assistant find a time | [test_circles.py](https://github.com/adeelahmad/lense/blob/main/fastapi_backend/tests/api/test_circles.py) `test_when_people_are_free`; [circles-ui.test.tsx](https://github.com/adeelahmad/lense/blob/main/nextjs-frontend/__tests__/circles-ui.test.tsx) `lets a circle see when you're free in one click` |
| Circles reach people on other servers only once an admin and the person turn it on: shares go to them signed, and theirs are taken only signed, recent and from someone in a circle | [test_federation.py](https://github.com/adeelahmad/lense/blob/main/fastapi_backend/tests/api/test_federation.py) `test_off_until_turned_on_and_findable`, `test_people_elsewhere_get_shares_and_send_them`, `test_notes_from_people_in_a_circle_only`; [circles-ui.test.tsx](https://github.com/adeelahmad/lense/blob/main/nextjs-frontend/__tests__/circles-ui.test.tsx) `makes you findable, and adds someone elsewhere by handle with Enter` |
| Someone's agent answers a question only from the namespaces they let that circle ask about, citing them, and they see it | [test_circles.py](https://github.com/adeelahmad/lense/blob/main/fastapi_backend/tests/api/test_circles.py) `test_asking_their_agent`; [circles-ui.test.tsx](https://github.com/adeelahmad/lense/blob/main/nextjs-frontend/__tests__/circles-ui.test.tsx) `lets a circle ask your agent about the namespaces you pick` |

## See what it costs
Expand Down
Loading
Loading
0