76 lines
3.2 KiB
JavaScript
76 lines
3.2 KiB
JavaScript
/**
|
|
* NetworkProvider interface — the documented contract for DashCaddy
|
|
* Private Network providers (DC-140, specs/PRIVATE-NETWORK-SPEC.md §3).
|
|
*
|
|
* Everything above the provider (people, groups, resources, access map,
|
|
* forward_auth, Technitium names, the CA, the UI) is shared and talks to
|
|
* the network ONLY through this contract — never to a provider module
|
|
* directly. Resolution goes through src/network/registry.js.
|
|
*
|
|
* ## Capability flags
|
|
*
|
|
* `capabilities()` returns:
|
|
* - invites provider can mint invite URLs itself (TS user-invites /
|
|
* WG one-time token). When false, DashCaddy mints its own.
|
|
* - splitDnsApi provider exposes a split-DNS API (Tailscale does;
|
|
* WireGuard writes Technitium directly instead).
|
|
* - perPeerFirewall provider enforces per-peer rules natively (WG nftables;
|
|
* Tailscale relies on ACLs, so false).
|
|
* - selfHosted no outside control-plane dependency (WG true, TS false).
|
|
*
|
|
* Feature modules MUST check capabilities and degrade cleanly.
|
|
*
|
|
* ## Methods (all async, all return plain JSON, all validated)
|
|
*
|
|
* id() → 'tailscale' | 'wireguard'
|
|
* capabilities() → { invites, splitDnsApi, perPeerFirewall, selfHosted }
|
|
* getStatus() → provider health/summary (TS: local `tailscale status`;
|
|
* WG: `wg show dump` + iface state)
|
|
* listDevices() → device list merged with local online state
|
|
* listPeople() → provider users projected to
|
|
* { id, displayName, email, createdAt }
|
|
* createInvite({ role, email? }) → { inviteUrl, id } — email is OPTIONAL;
|
|
* when omitted, the provider returns a link without sending
|
|
* (link-first, DC-085 pattern; never log inviteUrl raw)
|
|
* revokeInvite(id) → { revoked: true }
|
|
* blockPerson(userId) → reversible network-level block (TS: expire every
|
|
* device key owned by the user; WG: drop peer + deny set)
|
|
* unblockPerson(userId) → reverse of blockPerson (TS: no-op at provider
|
|
* level, DashCaddy re-grants via syncAccess)
|
|
* removePerson(userId) → delete provider devices + revoke invites
|
|
* revokeDevice(deviceId) → expire/remove a single device's access
|
|
* syncAccess(accessMap, resources) → compile + dry-run + push provider
|
|
* rules (hash-guarded). Injected per provider in later DCs
|
|
* (TS ACL compiler = DC-148; WG nftables = DC-150).
|
|
* whois(ip) → which person owns the connecting device
|
|
* configureDns({ zone, server }) → split-DNS setup when splitDnsApi
|
|
*
|
|
* ## Error contract
|
|
*
|
|
* All failures throw ProviderError (src/network/errors.js) with a `code`
|
|
* and `retryable` hint. Providers map their native errors at the boundary
|
|
* so no provider-specific error type ever escapes this package.
|
|
*/
|
|
|
|
'use strict';
|
|
|
|
module.exports = {
|
|
/** Method names every provider must implement (documented contract). */
|
|
CONTRACT_METHODS: [
|
|
'id',
|
|
'capabilities',
|
|
'getStatus',
|
|
'listDevices',
|
|
'listPeople',
|
|
'createInvite',
|
|
'revokeInvite',
|
|
'blockPerson',
|
|
'unblockPerson',
|
|
'removePerson',
|
|
'revokeDevice',
|
|
'syncAccess',
|
|
'whois',
|
|
'configureDns',
|
|
],
|
|
};
|