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.
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.