Sharing

​

Objects and methods

​

The grant model

• Written by the owner on the collection object; each grant change produces a ShareNotification for the grantee and a recorded change for resync.
• Exercised through the shared: indirection: a grantee addresses the owner’s data with the granted account id in the standard JMAP accountId slot; the session’s accounts object lists what is reachable. Capabilities resolve on the authenticated caller, data residency on the owner — usurpation is not representable in the request shape.
• Fail-closed. Shared-account dispatch denies by default; a rights lookup error refuses rather than granting.
• A composed call is admitted on its own. A method that runs another inside it (the /get behind Core/queryStream’s fetchProperties, the push patches, the alert snoozes) passes the shared-account gate and the admission of that inner method, exactly as if the client had sent it: inheriting the outer call’s context is not inheriting its admission. A grantee of one shared folder used to read the owner’s rules or contacts through Core/queryStream; the inner refusal now comes back as forbidden. The push patches no longer serve Thread/get, VacationResponse/get, EmailSubmission/get or CalendarEventNotification/get to a grantee, who receives a content-free StateChange instead. Each composed call also leaves its own row in the data access log, filed under the owner with the grantee as actor; on a strict organization, an answer whose row cannot be written is withheld (serverFail).
• A query stream stays on its account. Every page of a Core/queryStream opened on shared:<owner>, client-paced or pushed, is served from that account under the same admission as the first: a pushed stream used to serve page 1 from the owner and the following pages from the grantee’s own account. The cursor carries the account it was opened on and is refused invalidArguments on another; a grant withdrawn during the stream stops it at the next page with streamFailed, naming the error.

​

Account grants: a whole collection

• Every object of the collection, those created after the grant included: every mailbox, calendar, task list, notebook, the whole drive. readOnly reads; readWrite reads, writes and destroys items, each destruction written to the owner’s audit chain with the grant, and never shares, administers, sends mail or sends a scheduling message (a write only the grant admits that would send an invitation is refused). A row whose level reads admin, written outside the verb, is applied as readWrite, never more.
• Over JMAP only. IMAP, CalDAV and CardDAV open no object on an account grant; blob downloads, thumbnails and uploads follow the JMAP admission of the type.
• Never Contact. JMAP serves no contacts on a shared account, so a contact grant would announce an access that opens nothing: account grant --collection Contact is refused and says why. A team shares an address book through a tenant directory.
• Its states are its own. Every state served under a grant carries the grant’s fingerprint (method responses, composed calls, WebSocket, EventSource and push patches): a state obtained before the grant, under another grant or another level answers cannotCalculateChanges, and the client resyncs instead of reading a delta computed for different rights. Without a grant, states are unchanged byte for byte.

​

Teams and their address

​

Directory semantics worth knowing

• Principal types are honest. A shared team account’s principal is type: "other" (non-loginnable), never individual — people-pickers can rely on the type.
• Grantees must be human-backed, or a group. A grant to a principal backed by a non-loginnable account (a team’s own shared account, a resource, a location) is rejected at write time on every domain; a group is the one exception, since a grant keyed on a group resolves to its members at the access check, and membership is admin-only for exactly that reason.
• Destroying a principal purges its grants. A Principal/set destroy removes the grantee’s keys from every shareWith map — no dangling ACL entries — and warns or aborts if it would leave a shared drive without an eligible custodian.
• Erasure leaves tombstones. An erased person’s principal is PII-scrubbed but kept as a graph anchor, and a tombstoned principal is refused as a new grantee (compliance).
• A frozen account keeps the organization’s mandates, not its own. A grant carries who authored it: one the owner wrote is a mandate the account gave, suspended while the account is frozen (role: disabled), and reinstated with it; one the operator wrote in the owner’s name (account offboard --grant-mailbox-to, account grant, or the departure keys of Principal/setAdmin, see the admin API) is the organization’s decision and stays. A grant with no author is read as the owner’s, the fail-closed direction. A departure’s grant carries a mandatory expiry, at most one year out; account grant --until is optional, and refused toward a declared service account (service: true in the account capability object, v2:account, of the principal’s capabilities), a connector that never leaves (multi-tenancy).
• Entities are declared, never deduced. A person’s profileCard may name their employer in organizations by reference to a group (the group’s id under oximail.ch:principalId); the name is read from the group each time, so renaming it fixes every card. Only a group a tenant admin marked isEntity: true may be cited: Principal/set takes the mark at create and update, on a group only (invalidProperties otherwise, forbidden for a non-admin), and a card citing an unmarked group is refused naming the group. Principal/get always serves isEntity, and on a group cardReferenceCount, the cards that cite it, so a client knows before a rename or a destruction; withdrawing the mark of an entity cards still cite, or destroying it, is forbidden with the name and the count. Principal/query {filter: {isEntity: true}} is the employer picker’s source (false: everything but the entities). The console side is on the multi-tenancy page.
• Destroying a group frees its shared account, its reserved address and its seat, as destroying a resource or a location already did.
• A service account acting under shared:<owner> may patch only an allow-list of the principal, workingHours, photoBlobId and one key of one capability object, and only when its grant names the collection that opens that channel, not any write delegation; name, email and time zone stay closed. A photo set by anyone other than its person (that channel, or an administrator) must be an organization-wide blob the writer uploaded (/jmap/upload-tenant/{tenantId}) or can read, else invalidProperties with one text for every case (naming “this blob is in the person’s account” would be an oracle); each such set or removal is an audit line under the authenticated account.
• Principal/getAvailability (free-busy) is documented on the calendar page.

​

Across organizations: federation

"urn:oximail:params:jmap:federation": {
  "supportedGranteeKinds": ["realm"],
  "revocationIsForwardOnly": true
}

​

The grantee is an organization, not a person

​

Consent is not delegable

• Only the subject may create or modify a grant, acting on their own account. An administrator may revoke — revocation removes access, so an operator who must cut a leak does not wait for the subject — but never grant on someone’s behalf. A grant an administrator can create for you is not consent. The check is stricter than a role test: a request carrying shared access is somebody acting for someone else, whatever level it holds.
• Each write is one transaction: the grant row, the ShareNotification that tells the subject, and the audit row naming the writer commit together. The audit records who actually wrote it, not the account the request targeted, so an administrator’s revocation is never attributed to the subject.
• An unsupported granteeKind is refused loudly. "principal" parses as a well-formed request and would look accepted; the row it created would be a realm grant wearing a person’s name.

​

Why a grant may stop working, and how the subject learns it

• Revocation is unilateral and instant, and forward-only. A peer never reads or writes your grants; it learns of a revocation by being refused. That is what keeps revocation out of distributed-consistency territory — and it is also why revocationIsForwardOnly is advertised as data: revoking removes the read path going forward and undoes nothing already disclosed.
• The disclosure log is the other half of that sentence. FederationDisclosure is what makes “revoking undoes nothing already disclosed” checkable instead of merely reassuring: it survives the grant, and there is no FederationDisclosure/set at all, not even destroy-only. Recording a disclosure advances the subject’s collection state in the same transaction, so a client watching its own log sees it move. Retention bounds the log; the subject cannot erase it. It records disclosures, never attempts, so a peer that probes five hundred addresses creates no rows about the four hundred and ninety-nine people who never consented. Each row names the peer realm, the identity layer that was verified, the jurisdiction the grant stood under at that moment, and when it happened.