Files Bridge
How an agent's Home kept in a bucket is reached from its sandbox, and
the storage credential the bridge holds, both in link-store-contract.
Every bridge speaks link-sandbox-bridge's calls
(Bridges).
Reviewed Writes
Serving owners can enable Homes::reviews_writes and implement Homes::review_write with a shared interaction review. The default preserves the existing write policy. The source freezes owner, agent, team, path, bytes and expected object version before asking; it never holds an authority or storage lock across the owner wait. Read grants and independent resource policy continue to apply.
Commit the Reviewed Version
After review, the source takes the dispatch fence, reloads its binding and team grant, and claims only the exact prepared payload. The object write uses the frozen version or absence condition. A concurrent target change fails as a conflict, and revoked access prevents application. An unavailable source outcome stays Unknown. A backend without conditional writes cannot enable this review path around an unconditional write.
A storage credential
A bridge that reads and writes a cloud's storage for the agent is
handed a credential, never the cloud's own sign-in
(link_store_contract::authority::StoreSecret): {"token", "expires", "refresh_url", "refresh_token", "headroom_bytes"?}, an access token
sent as Bearer, when it ends (Unix seconds), where and with what to get
the next one, and, optionally, how many bytes it may still add.
Its refresh
link_store_contract::authority::Held refreshes the token with OAuth's own
refresh (RFC 6749, section 6: POST refresh_url, form-encoded,
grant_type=refresh_token&refresh_token=<grant>, answered
{"access_token", "expires_in", "headroom_bytes"?}) once two thirds of
its life have passed.
Where it refreshes
Over HTTPS, or HTTP only to this machine's loopback (127.0.0.1,
::1, localhost, by the address's parsed host), never following a
redirect.
Its room
It takes each answer's headroom_bytes as the room left. A write that
would pass it is refused before anything is sent (Held::reserve). A
refresh answered 400 or 401 ends the credential: every call after it
fails.
The files bridge
The files bridge (link_store_contract::files) serves an agent's Home
kept as objects in a bucket.
Its halves
Its client is the files-client feature of this crate (Link file's
bridge command, Link Memory's serve-many); its server half (serve,
Homes, DirStore, and Crypt, rclone's crypt format) is the
files-bridge feature, for whatever serves it, so neither tool builds
it. files is both.
Who serves it
No part of Link serves an agent's Home through the files bridge or runs
lnk-file-tool bridge, nor binds an agent's Home to lnk-memory-tool serve-many through it: a machine that runs agents only while they
answer, with Home in a bucket, does. An agent's own bridge serves one
for the agent's teams whose folders their services answer
(A team's folder elsewhere).
A team's folder
A read, write or list may name a team, <name> (a team of the
agent's own owner's, by the name its sandbox file's
[teams.<team>] gives it) or <account>/<name> (another
account's). A name never holds a / and an owner is an account's, so
the two forms never meet.
Reached at each call
It then reaches that team's folder instead of Home, as the server's
Homes::team gives it at that very call, never what was true when the
agent was bound, so an agent taken off a team, or a team renamed or
removed, is refused at its next call.
What it reads and writes
It reads the folders of it its grant writes or reads, writes only those
it writes (. for all of it), each from the version read, and lists
only what it reaches. Each write is told to the server
(Homes::team_changed), which keeps the team's memory current.
Its index
An index-get, index-put, index-list or index-delete naming a
team reaches the index kept beside that team's folder, in the folder's
storage, the team's memory's. Since the index tells what's anywhere in
the folder, it's read only by a member granted all of it (., read or
written), and written or deleted only by one writing all of it that the
server lets keep it (TeamFolder::keeps_index, as whoever pays for it
says), only as the index's own objects (<engine>/manifest.json and
its segments), within TEAM_INDEX_MAX. InTeam is the caller's side, a store named as
Home's is.
Store capacity
Store::put_bounded and delete_bounded ask for atomic shared-prefix
capacity. A store without that authority refuses before mutation.
Team index mutation uses these operations, without an unlocked listing.
DirStore keeps prefix counts under its cross-process folder lock,
syncing a dirty record before mutation and the completed count after.
Recovery recounts interrupted writes; ordinary writes to a registered
prefix preserve the same bound. Separate handles share its count.
Membership authority
Every call naming a team passes one check of the member's grant
(team_allows) before anything of the folder is reached. A call's
unknown field is refused, never ignored.
A team's folder elsewhere
A team whose folder the bridge neither holds nor checks, such as a
hosted team's folder in its owner's bucket reached by a member on its
own machine, is answered by that folder's service. Homes::remote_team
names the service at each call naming the team, before Homes::team,
and RemoteTeam hands the call on. The folder's secret and storage
credential stay with the service, never on the member's machine.
The route
Each call is a POST to team_route(owner, team) under the service's
URL, /v1/teams/<owner account>/<team ID>/files, whose body is the
call's Action as JSON with its team left out. A success answers the
Answer the bridge would. A refusal answers its status with the
bridge's Failure envelope, 409 for a conflict, which the member's
client meets as the bridge's own conflict.
The member's token
The call carries the member's own access token as Authorization: Bearer, made outside the sandbox by its machine for the service's host
with member_grants(team), team.member@team:<id>
(RemoteTeam::for_agent, the way the secret bridge makes an agent's
token). The bridge keeps it until a minute before it ends, and it
never enters the sandbox.
The service's checks
The service takes no identity from the call's body. It derives the
member from the verified token, reads the team's roster at that call,
and answers through TeamCalls, the bridge's own checks
(team_allows, the member's team_role) for the folder as that member
reaches it now. A member taken off the team is refused at its next
call. A write its source reviews is refused there, since a review needs
an agent bound to a bridge.
On the member's own machine
RemoteTeams is the Homes of a bridge serving one agent's teams kept
elsewhere, by the names the agent gives them, and no Home. It takes only
that agent's calls, and reaches a team only while the team's file there
still lists the agent, asked at each call. RemoteTeam::with_grant
holds each call first to what the agent is granted there, its sandbox
file's folders with its roles', by the bridge's own team_allows. The
service then checks the call again as the member its token names.