Acequia: Domain-Centric Authentication and Authorization concepts

stephen's chat scratchpad summaries not deeply reviewed - for discussion purposes only

Section 0: Onboarding

An Acequia-compliant app begins with a user invitation via a specific URL. Upon visiting this URL, a new user can generate a GUID and establish a public/private keypair.

The private key is securely stored in the browser sandbox using IndexedDB.
Later, this key can be optionally backed up to user devices, within the same-domain sandbox, preserving privacy and control.
The Acequia app may sync a cache of known public keys to peer devices to facilitate future authenticated communication.

This onboarding flow ensures local-first identity setup with zero dependency on centralized identity services, aligning with Acequia’s distributed philosophy.

Section 1: Authentication

Authentication is handled in-browser via Service Workers and client-side logic. The user proves their identity by presenting a signed challenge using their private key or credential.

Secure sessions (e.g., WebRTC DataChannels) can be established using mutual key exchange and challenge-response protocols. Once verified, these channels remain trusted for the duration of the session, eliminating the need for per-request reauthentication.

Section 2: Authorization

Authorization is file- and URL-based, governed by adjacent metadata files (e.g., .auth.json) stored alongside content.

Authorization logic executes in-browser, beginning with Service Workers and extending to OS-level Acequia nodes.
Metadata may live in browser cache, IndexedDB, the local file system, or peer-hosted WebDAV folders — in that order of access preference.

Auth File Example

{
  "read": ["alice@redfish.com", "publicKey:abc123", "phone:+15554443333"],
  "write": ["passkey:xyz789", "authApp:user123"],
  "admin": ["stephen@redfish.com"],
  "2fa": {
    "read": ["authApp"],
    "write": ["phone:sms", "email"]
  }
}

These files do not assume any specific identity framework. Supported identifiers may include: email addresses, public keys, WebAuthn credentials, SMS-confirmed phone numbers, or other implementation-defined tokens.

Access is hierarchical: the closest .auth.json file governs the file or folder, falling back to parent directories if none is found.

After secure channel authorization, subsequent file access may bypass per-request checks, relying on the verified session context.