<!-- source: https://docs.dreamlake.ai/dreamfs-authority @ 0.1.192 b2f973b1 -->
# DreamFS authority transport

This contract is under development and review. It is not a statement about the
deployed Source service or production durability. Source upload authorization
alone does not qualify a DreamFS authority.

DreamFS uses one approved Source and a reserved `.dreamfs/v1/<repository-id>`
prefix for both consumers. A repository id is exactly one canonical path
segment. All upload entry points enforce create-only writes beneath that root;
only `refs/dreamfs/<repository>/tips/<name>` accepts If-Match. Ordinary uploads,
including multipart uploads, cannot bypass this policy by omitting conditions.
Managed object/directory deletion of reserved data or its named ancestors is
refused. A root directory cleanup remains supported but skips reserved history
at storage deletion time, including authority data created after cleanup was
queued. Its deleted count includes only eligible objects.
Deleting the entire Source ends the repository lifetime and is an explicit
Source administration action, not cache eviction. Backend owners must confirm
that no out-of-band deletion/lifecycle policy removes live repository history.
Runtime prefix confinement is not a user authorization boundary: a user with
Source EDIT may authorize other repository prefixes in that Source. An actual
denied Source/principal or exact-capability path tampering is required for
isolation evidence, with the kind of boundary stated in the receipt. Its
configuration names the Source identity, canonical prefix, control-plane HTTPS
origin and an approved credential configuration reference. Never put credential
values or signed URLs in repository configuration, Memos or receipts. A content
hash does not grant access. Authorize every capability through normal Source
access and lifecycle checks; capabilities are short-lived and exact-path.

## Conditional single-object upload

An upload file may carry exactly one optional precondition:
`ifNoneMatch: "*"` for atomic create-only publication, or `ifMatch` containing
one quoted opaque ETag from the GET that returned the ref bytes. Conditions
must never be silently discarded. Conditional uploads are limited to the
64 MiB single-PUT boundary; multipart conditions are rejected before any
multipart initiation. DreamFS chunks and metadata must fit this limit.

The service binds the condition into the storage request signature and returns
it in the required request headers. The client sends those headers unchanged.
An S3 precondition failure is a conflict; an HTTP 409 is a conflict rather than
proof that this writer committed. A timeout or lost response after PUT remains
ambiguous. Reconcile by observing authority; never automatically retry a
mutable ref write into a misleading conflict. Immutable duplicate bytes still
require bounded verification of the existing object and Bao sidecar.

## Bounded observation

`POST /namespaces/:ns/sources/:sourceId/managed-read-capabilities` takes one
canonical `path` and returns an exact internal-object GET capability. It checks
Source USE and active lifecycle, never resolves an external layer, and sends
`Cache-Control: no-store` even on errors. The storage GET decides whether the
object is missing. This route is unreleased until the reviewed service lands.

Read bytes and the opaque conditional-write ETag from the same storage GET
response. A separate Source Stat response is not a validator for later GET
bytes. Enforce an aggregation cap before allocating a complete body, including
unknown-length and dishonest-length responses. Ref bodies are capped at their
wire size; oversized, malformed or validator-free responses fail explicitly.
Missing is distinct from unauthorized, unavailable and corrupt.

Read and write capabilities stay in memory. Refresh through normal authorized
control-plane requests after expiry; do not persist signed URLs. Preserve
request outcome ambiguity through every retry and cache decorator. Clean
cache reads never establish current ref state. External Source layers must
not supply authoritative DreamFS objects when internal objects are absent.

## Activation and legacy capabilities

Legacy `/dreamdb/sign`, `/dreamdb/ref` and `/dreamdb/credentials` routes are
absent when the Source v1 surface is selected. The shared startup surface guard
refuses mixed legacy/v1 route registration, including otherwise non-overlapping
legacy write routes. Production qualification must verify the legacy signer is
absent; it must not infer disjoint storage solely from different database models.
Previously issued legacy STS credentials and direct privileged S3 writers remain
out-of-band authorities until their actual expiry or an authorized operator fence.
No IAM role, grant or session policy is changed by this contract.

Previously issued unconditional upload capabilities remain valid until their
original expiry (currently one hour). Deploying this validation does not revoke
those capabilities. Mixed old/new service instances can also issue different
contracts during rollout. Verify the new service revision and old-writer drain;
for previously used repository prefixes, wait until every legacy capability can
have expired before asserting server-enforced conditional authority.

Acceptance may use a fresh, unpredictable repository prefix which has never had
a legacy upload capability issued, after the new contract is observed active.
Record that limitation and retain all test objects. Fresh-prefix results do not
prove immediate protection of previously issued capabilities or other prefixes.
Do not alter bucket policies, grants or identities to manufacture a cutover.

## Production acceptance

Use existing approved infrastructure only. The backend owner must confirm
durable object completion, atomic create-only and If-Match conditions, and
retention of immutable closure and historical roots. Qualify concurrent
publication, stale validators, response loss after commit, restart readback,
bounded malformed/corrupt reads, and authorization scope isolation on the
exact service and consumer commits. Keep sanitized receipts and pending
journals on failure. An approved denied scope is an explicit input to the
negative control, not permission to explore other repositories.

FsConnector lacks file/directory fsync and does not establish power-loss
durability. Loopback tests, cold CLI object transfer and green CI do not
replace production acceptance or independent review.

### Existing-service qualification command

Core maintains a credential-redacted control harness for the existing
`geyang/dreamfs-linux-acceptance` Source. It requires the exact reviewed runtime
revision, refuses writes before runtime identity and managed-read contract
checks, and creates only a fresh reserved repository prefix. Its private
auth provider and CLI build are pinned in the approved Core workspace.

```bash
DREAMFS_CORE_WORKSPACE=/absolute/approved/core-workspace \
DREAMFS_EXPECTED_SERVICE_REVISION=<reviewed-full-deployed-sha> \
node dreamlake-server/scripts/dreamfs-authority-acceptance.mjs
```

The script retains all test objects and emits only sanitized control results.
It tests exact-capability path isolation, not a denied user/Source boundary.
Its discarded acknowledgement/readback control is not an actual network-drop
fault; Linux/LFS own the process/journal response-loss acceptance. Genuine
GET capability expiry takes approximately five minutes and remains in memory.
This command has not qualified production until its real receipt is recorded.
