DreamLake

Cross-namespace mounts

This reference describes the implementation branch for issue #1339. It does not establish that these routes are deployed. The interface is the REST API only; no CLI or Web support ships with it.

An ordinary attach requires the resource and the Project to share a namespace. The only other way to mount a resource is an external mount grant: the resource's namespace owner authorizes one exact foreign Project, and someone who can add content to that Project accepts it by mounting.

Who can do what

ActionRequired authority
Issue or revoke a grantNamespace OWNER of the resource's current namespace, who also holds that resource's own sharing authority. Organization MEMBER, Project ADMIN and resource ADMIN cannot.
Accept (mount)Content-create permission on the target Project.
UnmountContent-delete permission on the target Project. Works even when the grant is no longer valid.

A former owner of a moved resource cannot issue or revoke its grants; the resource's current owner sees and cleans up every grant, including inert ones.

Audience: what the owner agrees to

Every issue request must send "audience": "project"; there is no default. It authorizes every current and future reader of that exact Project, including users added later, team grants and, for an organization Project, every organization member's baseline READ. maxRole caps what they get:

  • READ or WRITE content access only. Workflows accept READ only.
  • Never sharing, deletion, ownership transfer, re-attachment to another Project, infrastructure credentials or workflow runs.

Project grant changes on the target Project are not blocked: the owner has consented to that Project's audience.

Separately, a caller with content-create permission on the admitted Project can label an existing Memo filing with one of that Project's Bindrs. This requires current Memo read access and a valid, unexpired mount grant; repeated tags run the same checks. It creates no new mount or audience and changes no grant terms. Other resource types and grant-admitted Memo labels in another Project remain unsupported. Revocation removes the filing and its labels together.

Routes

POST   /namespaces/:namespace/external-mount-grants
GET    /namespaces/:namespace/external-mount-grants?resourceType=artifact&resourceId=ID
DELETE /namespaces/:namespace/external-mount-grants/:grantId
GET    /namespaces/:namespace/projects/:projectSlug/external-mount-grants
POST   /namespaces/:namespace/projects/:projectSlug/resources   (with externalMountGrantId)
DELETE /namespaces/:namespace/projects/:projectSlug/resources

Issue a grant from the resource's namespace. resourceId is the database ID (an Artifact's id, not its artifactId); projectId is the target Project's stable ID, supplied by that Project's owner, and projectNamespace is the namespace that Project must be in.

Issuing never looks the target Project up, so the response is the same whether or not a private Project with that ID exists. The grant is validated when it is accepted: the Project must be live in projectNamespace at that moment. A Project that moves before or after issue no longer matches, so the grant can't be accepted and stops admitting reads.

bash
curl -X POST "$API/namespaces/acme/external-mount-grants" -H "authorization: Bearer $TOKEN" \
  -H 'content-type: application/json' \
  -d '{"resourceType":"artifact","resourceId":"6ad9…","projectId":"6ad8…","projectNamespace":"lab","audience":"project","maxRole":"READ"}'

201 creates a grant. Re-sending identical terms returns the same active grant with 200 after all checks run again. Different terms while one is active return 409 EXTERNAL_MOUNT_GRANT_EXISTS: revoke it and issue a new one.

The target Project lists offers with GET …/projects/:projectSlug/external-mount-grants and accepts one by mounting:

bash
curl -X POST "$API/namespaces/lab/projects/robots/resources" -H "authorization: Bearer $TOKEN" \
  -H 'content-type: application/json' \
  -d '{"resourceType":"artifact","resourceId":"6ad9…","externalMountGrantId":"6ada…"}'
ErrorMeaning
400 EXTERNAL_MOUNT_AUDIENCE_REQUIREDaudience was not sent as "project".
400 EXTERNAL_MOUNT_ROLE_UNSUPPORTEDmaxRole other than READ/WRITE, or WRITE for a workflow.
400 EXTERNAL_MOUNT_SAME_NAMESPACEUse an ordinary attach instead.
403 LOST_AUTHORITYThe caller is not the namespace owner.
404 NAMESPACE_NOT_FOUNDprojectNamespace does not exist.
409 EXTERNAL_MOUNT_CONFLICTAn ordinary attach found a grant-admitted mount of the same resource; unmount it first.
404 EXTERNAL_MOUNT_GRANT_NOT_FOUNDUnknown, revoked, expired, for another Project or resource, or the Project has moved.
409 EXTERNAL_MOUNT_TAGGING_UNSUPPORTEDThe grant-admitted resource is not a Memo, or the Bindr is outside the admitted Project.

Grant lifecycle

Grant terms (resource, owner, target Project and its namespace, audience, maxRole, expiresAt) never change. Each change is a new grant with a new ID, which must be accepted again.

  • Restore. Unmounting removes only the node. While the same grant is active and unexpired, mounting again needs no new approval.
  • Revoke. Deletes every mount the grant admitted and its Bindr tags in one transaction. Only access derived from that grant ends; the resource's own links, shares and other Project grants are unaffected.
  • Inert grants. A grant stops admitting reads as soon as it is expired, the resource is deleted or leaves the issuing namespace, or the Project leaves the namespace it was issued for. It is never carried to a new owner or audience.
  • No fallback. A grant-admitted mount is authorized only by its grant. If its resource later lands in the Project's own namespace, the mount does not become an ordinary mount with the Project's full roles. It stays inert until it is unmounted, after which the resource can be attached normally.
  • Deletion. Permanently deleting a Memo, or purging an Artifact, Scene or Annotation, revokes its grants and removes their mounts. Workflows have no permanent deletion; a soft-deleted workflow's grants are inert. IDs are never reused, so a new resource cannot inherit an old grant.
  • Soft delete. On a server with the issue #1343 fix (not yet released), a soft delete removes the grant's mounts but keeps the grant, inert while the resource is deleted. After a restore the Project can mount it again under the same active grant without a new approval.

Server-mediated reads are rechecked on every request, so revocation denies them immediately. Credentials issued before revocation keep their documented lifetime: Artifact read tokens up to five minutes, and resource-scoped upload credentials their issued TTL. Memo RTC room keys are never returned to clients; open Memo event streams recheck access every 15 seconds and close.

Ownership transfers

A transfer that changes who owns a resource, or who owns the Project holding a foreign mount, must dispose of every cross-namespace mount explicitly in policy.externalMounts. The preview lists them under externalMounts; the preview hash and the destination's acceptance bind that exact set, and the commit refuses with STALE_PREVIEW if it changed.

json
"policy": {"visibility": "private", "retainedGrantIds": [], "preserveAccess": true, "preserveExternalFilings": true,
  "externalMounts": {"apiVersion": 1, "dispositions": [
    {"kind": "outgoing-grant", "id": "GRANT_ID", "action": "reissue"},
    {"kind": "incoming-mount", "id": "NODE_ID", "action": "detach"},
    {"kind": "legacy-filing", "id": "NODE_ID", "action": "retain", "audience": "project", "maxRole": "READ"}
  ]}}
KindChangesActions
outgoing-grantOwner: a grant on a resource that movesreissue: revoke it and issue a new grant from the destination owner with identical receiver-facing terms, keeping its mounts. revoke: remove it and its mounts. A grant issued by an earlier owner can only be revoked.
incoming-mountReceiver: a foreign resource mounted in a moving Projectdetach only. The receiver never re-issues another owner's grant; that grant becomes inert.
legacy-filingOwner: a same-namespace Memo filing kept by preserveExternalFilingsretain: becomes a grant with the explicitly approved audience and maxRole instead of the legacy marker.

Malformed, duplicated or mismatched entries return 400 EXTERNAL_MOUNT_DISPOSITION_INVALID. A missing item is the preview blocker EXTERNAL_MOUNT_DISPOSITION_REQUIRED; an item no longer present is EXTERNAL_MOUNT_DISPOSITION_UNKNOWN. reissue and retain create grants, so the operation can be accepted only by the destination namespace OWNER (403 EXTERNAL_MOUNT_REISSUE_OWNER_REQUIRED).

reissue is refused with 400 EXTERNAL_MOUNT_REISSUE_SAME_NAMESPACE when the destination is the namespace that already holds the target Project. A grant cannot apply inside its own namespace, and the capped access is never silently turned into ordinary access. Choose revoke; after the move, the new owner can attach the resource to that Project as an ordinary resource. The preview marks these grants with targetInDestination: true.

Supported paths are whole-Project streaming transfers and standalone Memo, Artifact, Scene and Annotation transfers. Their existing limits still apply, for example a personal source namespace. Workflows, Sources and Infrastructure Stacks have no cross-namespace mount transfer; Sources and Stacks cannot be mounted across namespaces at all.

Compatibility

New requests that retain external Memo filings must use policy.externalMounts with a retain disposition for each one. A new request that sets preserveExternalFilings without it fails preview and creation with EXTERNAL_MOUNT_POLICY_REQUIRED, so no new legacy markers are created. Any grant or incoming mount also requires dispositions (EXTERNAL_MOUNT_DISPOSITION_REQUIRED). New requests that touch no external mounts are unchanged.

Operations stored before this release keep their original contract when accepted, committed or recovered, including the legacy marker and their original preview hashes. Fixed-manifest operations keep their recovery too. Existing legacy retained filings keep their current behavior and are not converted; converting one requires an explicit owner-issued grant.

CLI releases through 0.84 cannot send dispositions. Through those releases, a Project or Memo move that preserves external filings fails with EXTERNAL_MOUNT_POLICY_REQUIRED; use the API, or remove the filings first.

Preserving Memo transfer proposal (not released)

A separate, default-off singleton Memo transfer profile proposes external-mount policy version 2. It adds an explicit convert-local disposition for a grant whose Project is in the new owner's namespace. The existing node and folder remain in place, with a successor grant that retains its role ceiling and expiry. Only a completed, accepted preserving-transfer receipt can authorize that local grant; an ordinary external grant still becomes inert when its namespaces match. The existing version 1 contract is unchanged. See the unvalidated source contract for admission, principal preservation, public visibility, collision and verification boundaries. No client command or production availability is claimed by this proposal.