newdrive/docs/adr/0009-external-protocol-gateway-boundary.md

ADR-0009: External protocol gateway boundary

Status: Accepted

Context

Existing backup and automation tools may benefit from WebDAV or rclone compatibility. Managed Drive storage is not a user-visible filesystem: PostgreSQL owns hierarchy and revisions while the array contains opaque immutable blobs. Direct protocol access to object paths would bypass authorization, commit intents, change events, trash, replacement recovery, and audit.

Decision

• REST and application services remain canonical.
• A writable WebDAV gateway MAY be implemented post-v1 as a protocol translator. Every write calls normal application services, uses revision preconditions, creates normal audit/change records, and sends deletion to trash unless a credential explicitly permits permanent deletion.
• WebDAV uses independently revocable, action- and subtree-scoped credentials. Durable WebDAV lock tables are added with that module, not pre-created in the core schema.
• A native rclone backend MAY later call the REST API directly for richer hashes, modification times, resumable uploads, server-side move/copy, trash, and error semantics. Generic rclone-over-WebDAV and a native backend may coexist.
• Native rsync service, rsync staging ingestion, and direct SMB/SFTP access to managed object storage are not planned. Rsync may operate on a local folder maintained by a future desktop client, never on Drive's server object directory.
• No gateway may import storage adapters or mutate core repository tables directly (I16).

Integration configuration and lock tables are introduced only when their module is implemented. Phase 1 adds only the shared foundations already required by REST clients: client identity, persistent idempotency, mutation attribution, and scoped credentials.

Consequences

• Future compatibility does not force writable WebDAV or integration-specific tables into stable v1.
• Existing tools can gain interoperability later without weakening the immutable object model.
• A protocol gateway must provide streaming, conditional requests, bounded listings, authentication, audit, and revocation appropriate to that protocol.