<!-- source: https://docs.dreamlake.ai/api/external-mounts @ 0.1.192 b2f973b1 -->
# Cross-namespace mounts

This reference describes the implementation branch for
[issue #1339](https://github.com/dreamlake-ai/dreamlake-workspace/issues/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

| Action                  | Required authority                                                                                                                                                           |
| ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Issue or revoke a grant | Namespace **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.                                                                                                                             |
| Unmount                 | Content-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

```text
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…"}'
```

| Error                                    | Meaning                                                                                 |
| ---------------------------------------- | --------------------------------------------------------------------------------------- |
| `400 EXTERNAL_MOUNT_AUDIENCE_REQUIRED`   | `audience` was not sent as `"project"`.                                                 |
| `400 EXTERNAL_MOUNT_ROLE_UNSUPPORTED`    | `maxRole` other than `READ`/`WRITE`, or `WRITE` for a workflow.                         |
| `400 EXTERNAL_MOUNT_SAME_NAMESPACE`      | Use an ordinary attach instead.                                                         |
| `403 LOST_AUTHORITY`                     | The caller is not the namespace owner.                                                  |
| `404 NAMESPACE_NOT_FOUND`                | `projectNamespace` does not exist.                                                      |
| `409 EXTERNAL_MOUNT_CONFLICT`            | An ordinary attach found a grant-admitted mount of the same resource; unmount it first. |
| `404 EXTERNAL_MOUNT_GRANT_NOT_FOUND`     | Unknown, revoked, expired, for another Project or resource, or the Project has moved.   |
| `409 EXTERNAL_MOUNT_TAGGING_UNSUPPORTED` | The 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"}
  ]}}
```

| Kind             | Changes                                                               | Actions                                                                                                                                                                                                                     |
| ---------------- | --------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `outgoing-grant` | Owner: a grant on a resource that moves                               | `reissue`: 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-mount` | Receiver: a foreign resource mounted in a moving Project              | `detach` only. The receiver never re-issues another owner's grant; that grant becomes inert.                                                                                                                                |
| `legacy-filing`  | Owner: a same-namespace Memo filing kept by `preserveExternalFilings` | `retain`: 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](/dev/notes/note-ownership-gate/) for admission,
principal preservation, public visibility, collision and verification boundaries.
No client command or production availability is claimed by this proposal.
