connectors
Lets a satellite program on a customer’s own machine deliver files into the app. The satellite pairs through the OAuth device flow (RFC 8628): it shows a short code, a tenant admin confirms it, and the satellite receives a revocable ksat_ device token of which only the SHA-256 is stored. With that token it uploads files (raw bytes plus relative path, SHA-256 and modification time; the same file again is the same item) and sends heartbeats. Each upload becomes a file reference plus an event-sourced inbound-item; other features consume its created event. The HTTP endpoints are not handlers: mount createConnectorRoutes() from @cosmicdrift/kumiko-bundled-features/connectors as extraRoutes (they live outside /api, so the satellite needs no session). The wire protocol is described in docs/guides/connectors-satellite.md.
How it fits
Section titled “How it fits”What this feature needs to run (Requires, top) and the write commands this feature provides (Provides, bottom).
flowchart TB
n_connectors["connectors"]
subgraph how_reqs["Requires"]
n_files["files"]
n_tenant["tenant"]
n_tenant_lifecycle["tenant-lifecycle"]
end
subgraph how_provides["Provides"]
n_cmd_connectors_write_approve_device(["approve-device"])
n_cmd_connectors_write_check_device(["check-device"])
n_cmd_connectors_write_claim_authorization(["claim-authorization"])
n_cmd_connectors_write_delete_file(["delete-file"])
n_cmd_connectors_write_delete_folder(["delete-folder"])
n_cmd_connectors_write_device_poll(["device-poll"])
n_cmd_more(["+8 more"])
end
n_files --> n_connectors
n_tenant --> n_connectors
n_tenant_lifecycle --> n_connectors
n_connectors --> n_cmd_connectors_write_approve_device
n_connectors --> n_cmd_connectors_write_check_device
n_connectors --> n_cmd_connectors_write_claim_authorization
n_connectors --> n_cmd_connectors_write_delete_file
n_connectors --> n_cmd_connectors_write_delete_folder
n_connectors --> n_cmd_connectors_write_device_poll
n_connectors --> n_cmd_more
Provides — write commands this feature registers (dispatch them through the command bus):
connectors:write:approve-deviceconnectors:write:check-deviceconnectors:write:claim-authorizationconnectors:write:delete-fileconnectors:write:delete-folderconnectors:write:device-pollconnectors:write:device-startconnectors:write:mark-device-checkedconnectors:write:mark-device-retryconnectors:write:receive-fileconnectors:write:request-retryconnectors:write:revokeconnectors:write:revoke-device-tokensconnectors:write:touch-device
Dependencies
Section titled “Dependencies”- Requires:
files,tenant,tenant-lifecycle - Activation: always on (not toggleable)
Extensions & cross-feature APIs
Section titled “Extensions & cross-feature APIs”- Registers extension:
tenantData→inbound-folder,tenantData→connector,tenantData→inbound-item