rightkit_daemon/
lib.rs

1//! rightkit-daemon: the one discovery and authentication convention for local
2//! Right Suite services (the shared speech service, the in-app control server,
3//! `right-ctl`).
4//!
5//! * **Discovery** - `<suite>/runtime/<service>/service.json`, written
6//!   atomically after the endpoint is listening, removed on clean exit. A
7//!   record whose endpoint does not answer is stale and ignored.
8//! * **Ranking and takeover** - one host per service per suite. A would-be host
9//!   that outranks the incumbent (lower rank wins) writes `takeover.json`; the
10//!   incumbent stops admitting work, finishes or hands off in-flight requests
11//!   with the retryable [`ERROR_HOST_HANDOFF`] at their next boundary, and
12//!   releases. Clients re-read discovery and resubmit. The incumbent looks for a
13//!   request from another process once a second (a stat of `takeover.json`, no
14//!   thread polls faster), so a takeover starts up to about a second after the
15//!   request is written.
16//! * **Authentication** - no TCP and no bearer tokens. Unix: a socket in a 0700
17//!   directory, mode 0600, and the kernel-reported peer uid (`getpeereid` on macOS
18//!   and the BSDs, `SO_PEERCRED` on Linux) checked on every accept and by every
19//!   client (`verify_peer_is_current_user`); a platform that cannot check refuses
20//!   every peer. Windows: a named pipe whose DACL grants only the current user's SID
21//!   (`owner_only_security_attributes` on Windows), remote clients rejected, first-instance
22//!   flag set against name squatting, a bounded instance count
23//!   ([`HostOptions::max_pipe_instances`]), the client's process-token SID checked on
24//!   every accept, and clients opening with `SECURITY_IDENTIFICATION` and checking
25//!   the server's SID. See the README threat model.
26//! * **Verifying the host** - the transport proves a host runs as the current user, not which
27//!   program it is. [`Client::connect_expecting`] takes a [`HostExpectation`] (the executable the
28//!   host may be, for example a sibling inside the client's own app bundle), asks the kernel who
29//!   is on the listening end of the connected socket (macOS `LOCAL_PEERPID` and `proc_pidpath`,
30//!   Linux `SO_PEERCRED` and `/proc/<pid>/exe`), and refuses anyone else with a typed
31//!   [`HostIdentityError`] before the `hello` or any request is written. [`Client::connect`] stays
32//!   unauthenticated-host. [`ClientConfig::ignore_env_overrides`] makes the suite root come only
33//!   from the account database, so a launcher's environment cannot redirect a release client.
34//!   See the README, "Verifying the host".
35//! * **Per-app request allowlist** - each client names its app in `hello`; an
36//!   app may call only the methods listed for it (the generalisation of
37//!   HeardRight's `SERVICE_ALLOWED_SCHEMAS`). The app label is an allowlist key,
38//!   not a security boundary against code already running as the same user.
39//! * **Fail-closed roots** - [`Suite::resolve`] errors when no absolute
40//!   app-data root can be determined; it never falls back to the working
41//!   directory. [`Suite::per_run_temp`] is the explicit opt-in alternative.
42//!
43//! Wire format: bounded JSON lines (`rightkit-sidecar`), the same frames
44//! as the `rightkit-job-queue` engine contract:
45//! `hello`, `request{id,method,params}`, `event{id,event}`, `response{id,ok,result|error}`.
46
47#[cfg(feature = "agent_daemon_core")]
48pub mod agent_daemon_core;
49#[cfg(feature = "agent_daemon_runtime")]
50pub mod agent_daemon_runtime;
51mod app_root;
52/// Approval workflow mechanics: request binding, verified decisions, one execution claim,
53/// audit before effect (PK07-4).
54pub mod approval;
55mod attach;
56pub mod chunk;
57mod client;
58pub mod contract;
59mod discovery;
60mod error;
61pub mod event_log;
62mod fail_limit;
63mod host_identity;
64mod incumbent;
65pub mod install;
66pub mod lifecycle;
67#[cfg(feature = "link")]
68pub mod link;
69/// Loopback-only HTTP host with a bearer token (`remote-loopback` feature, not `remote`).
70#[cfg(feature = "remote-loopback")]
71pub mod loopback;
72pub mod metrics;
73pub mod mode;
74mod peer;
75mod peer_signature;
76pub mod private;
77mod record;
78mod registration;
79#[cfg(feature = "relay")]
80pub mod relay;
81pub mod reload;
82/// Daemon host (`remote` feature) and device client (`link` feature); see the module docs.
83#[cfg(any(feature = "remote", feature = "link"))]
84pub mod remote;
85mod root_cutover;
86mod server;
87mod service;
88mod shutdown;
89pub mod stop;
90mod suite;
91pub mod supervisor;
92mod takeover_watch;
93pub mod ticker;
94mod transport;
95pub mod wake;
96
97pub use attach::{attach_or_fallback, Attached};
98pub use client::{Client, ClientConfig, ClientPool, RetryPolicy, DEFAULT_DEADLINE};
99pub use discovery::{
100    adopt_or_spawn, discover_apps_in, discover_apps_in_with, discover_macos, discover_macos_with,
101    discover_windows, discover_windows_with, parse_plist_string, parse_reg_query, plan_host,
102    poll_until, publish_takeover, record_process_matches, resolve_install_dir, resolve_rank,
103    should_request_takeover, spawn_detached, takeover_obliges_yield, try_adopt_or_spawn,
104    try_plan_host, wait_for_claim_winner, AdoptOrSpawn, Completeness, DiscoverOptions, HostPlan,
105    InstalledApp, SpawnClaim, SpawnClaimError, UninstallEntry,
106};
107pub use private::{
108    exit_when_stdin_closes, watch_reader_eof, watch_stdin_eof, PrivateChild, PrivateSecret,
109    SecretError, SECRET_BYTES, SECRET_HEX_LEN,
110};
111// Deprecated items stay exported for existing callers; their deprecation is reported at the
112// caller's own use site, not on this re-export.
113pub use app_root::{
114    valid_app_name, AppRoot, AppRootError, LinkNotCreated, MigrateOptions, MigratedLink,
115    MigrationOutcome, MigrationReport, MigrationScope, MigrationState, MigrationStatus,
116    OmittedLink, ReparseKind, SkippedReparsePoint, SkippedSpecial, SpecialKind, WriterLock,
117    MAX_APP_NAME_LEN, MIGRATION_MARKER, MIGRATION_STATE,
118};
119#[allow(deprecated)]
120pub use discovery::{discover_apps, KNOWN_APPS};
121pub use error::{
122    ConnectError, ServiceError, ERROR_BAD_CHUNK, ERROR_CONNECTION_CLOSED, ERROR_FORBIDDEN,
123    ERROR_HOST_HANDOFF, ERROR_HOST_IDENTITY, ERROR_NOT_ALLOWED, ERROR_RATE_LIMITED,
124    ERROR_REQUEST_TOO_LARGE, ERROR_RESPONSE_TOO_LARGE, ERROR_REVISION_CONFLICT,
125    ERROR_SUITE_UNRESOLVED, ERROR_TIMEOUT, ERROR_UNAUTHENTICATED, ERROR_UNAVAILABLE,
126};
127pub use fail_limit::FailLimiter;
128pub use host_identity::{HostExpectation, HostIdentityError, HostIdentityReason, HostProcess};
129pub use incumbent::{stop_incumbent, IncumbentError, IncumbentStop};
130pub use lifecycle::{
131    DaemonLifecycle, LifecycleError, Provenance, ERROR_NOT_OWNED, ERROR_RESTART_EXHAUSTED,
132    ERROR_SESSION_RELEASED, ERROR_STALE_GENERATION,
133};
134#[cfg(unix)]
135pub use peer::verify_peer_is_current_user;
136#[cfg(windows)]
137pub use peer::{
138    current_user_sid, owner_only_security_attributes, owner_only_security_attributes_with,
139    pipe_security_attributes, verify_pipe_peer_is_current_user, verify_pipe_peer_is_sid,
140    verify_pipe_server_is_current_user, OwnerOnlySecurityAttributes,
141};
142pub use peer::{
143    AclEntry, IntegrityLabel, PeerError, PeerFailureKind, PeerIdentity, PeerRefusal,
144    ACCESS_GENERIC_ALL, ACCESS_PIPE_OWNER_RW,
145};
146pub use peer_signature::{
147    verify_authenticode, verify_peer, AuthenticodeSigner, PeerPolicy, SignatureError,
148    SigningIdentity, LICENSE_SNAPSHOT_METHOD,
149};
150pub use record::{
151    clear_takeover_if_owner, read_live_record, read_record, read_takeover, record_path,
152    takeover_path, try_read_live_record, try_read_record, try_read_takeover, write_atomic,
153    write_takeover, Allowlist, ServiceRecord, TakeoverRequest, PROTOCOL_MAJOR, PROTOCOL_MINOR,
154    RANK_UNKNOWN,
155};
156pub use registration::{
157    MethodDescriptor, Registration, RegistrationError, ServiceIdentity, TransportProfile,
158};
159pub use root_cutover::{
160    CutoverContext, CutoverError, CutoverParticipant, CutoverPhase, CutoverReport, CutoverStep,
161    FsMove, ParticipantError, RecoverOutcome, RetireMode, Retired, RootCutover, RootSelection,
162    RootStatus, Settlement, CUTOVER_RECORD,
163};
164pub use server::{
165    host, host_with_options, CallContext, Emit, Handler, HostError, HostOptions, Hosted,
166    ServiceConfig, ServiceEvent, ServiceStatus, DEFAULT_FRAME_LIMIT, DEFAULT_HANDSHAKE_TIMEOUT,
167    DEFAULT_MAX_CONNECTIONS, DEFAULT_RESERVED_SLOTS, DEFAULT_WRITE_TIMEOUT,
168};
169pub use service::{BuildError, Service, ServiceBuilder};
170pub use shutdown::{OrderedShutdown, PhaseOutcome, PhaseReport, ShutdownReport};
171pub use suite::{
172    valid_service_name, Suite, SuiteError, ENV_SUITE_ROOT, MAX_SERVICE_NAME_LEN, SHARED_DIR_NAME,
173    SUITE_DIR_NAME,
174};
175pub use transport::{
176    endpoint_candidates, endpoint_for, find_live_endpoint, open_stream, open_stream_expecting,
177    pid_alive, probe_endpoint, try_endpoint_for, Accepted, Conn, EndpointError, Listener, Stream,
178    DEFAULT_MAX_PIPE_INSTANCES, MAX_UNIX_SOCKET_PATH,
179};
rightkit_daemon/lib.rs

rightkit_daemon/
lib.rs
