Skip to content
alpha 0.1.0-alpha.7 is on crates.io. Install the CLI Start here

0022 - Deep links

Status: Implemented (2026-11-18; initial and forwarded arguments are wired; macOS bundle registration is packager-owned)

Phase 2 needs apps to accept URL-scheme launches. This spec fixes the deep-link service contract: scheme validation, registration, parsing and a queue that waits for the app. The auro::services re-export requires the facade's services feature.

Scope

  • auro-services::register_scheme: register a scheme for the current user.
  • auro-services::AppLinks: parse accepted schemes and queue links until drained.
  • DeepLink: scheme, host, decoded segments, decoded query and raw argument.
  • auro::services::AppLinks and register_scheme re-exports.
  • App::deep_links(links): queues initial process arguments and forwarded InstanceMessage arguments into a shared queue.

Out of scope

  • macOS CFBundleURLTypes editing; the packager owns the bundle's Info.plist.
  • Linux .desktop installation by the packager; the service writes a user entry and calls xdg-mime.
  • Authentication, consent prompts and unknown-origin policy.
  • Universal links / HTTPS associations.

Decisions

D1 - A closed scheme list

AppLinks::new takes the accepted schemes. parse rejects any other scheme, control characters, links over 4096 bytes, empty hosts and ./.. path segments. The app sees only links it asked for. register_scheme validates the RFC 3986 grammar: the first character is ASCII alphabetic and the rest are ASCII alphanumerics or +, -, .. A leading digit and _ are rejected; + is accepted.

D2 - Registration is per user

register_scheme always acts in the current user's namespace:

PlatformMechanism
WindowsHKCU\Software\Classes\<scheme> via reg.exe
LinuxXDG desktop entry plus xdg-mime default
macOSpackager's CFBundleURLTypes; the call is a no-op

The Linux entry's Exec value quotes the executable and escapes it for the Desktop Entry spec: % -> %% (field codes expand even inside quotes), "/\/`/$ are escaped, and control characters (including \n) are rejected so a path cannot inject another key.

Rejected: writing machine-wide registry keys or system desktop files. They need elevation and are not appropriate for an app-level link.

D3 - Queue until the app asks

Links arrive from launch arguments and may arrive before the UI is ready. AppLinks stores parsed links in a mutex-protected FIFO and returns them in arrival order on drain. Callers can ignore duplicates themselves; the queue does not deduplicate.

D4 - Parsing is defensive

Percent decoding is UTF-8-aware. Control characters are rejected after decoding. Path traversal is rejected before the app sees a segment. Invalid links are dropped, not turned into partial links.

Rejected: handing raw strings to every app. Every consumer would re-implement the same checks.

Interfaces

#![allow(unused)]
fn main() {
pub enum DeepLinkError { Register(String), InvalidScheme(String) }

pub struct DeepLink {
    pub scheme: String,
    pub host: String,
    pub segments: Vec<String>,
    pub query: BTreeMap<String, String>,
    pub raw: String,
}

pub fn register_scheme(
    scheme: &str,
    executable: &std::path::Path,
) -> Result<(), DeepLinkError>;

pub struct AppLinks { /* queue, schemes */ }

impl AppLinks {
    pub fn new(schemes: Vec<String>) -> Self;
    pub fn push(&self, raw: &str);
    pub fn push_raw(&self, raw: &[String]);
    pub fn drain(&self) -> Vec<DeepLink>;
    pub fn schemes(&self) -> &[String];
}

impl App {
    #[cfg(feature = "services")]
    pub fn deep_links(self, links: AppLinks) -> Self;
}
}

Usage:

let links = auro::services::AppLinks::new(vec!["myapp".to_owned()]);
App::new()
    .deep_links(links.clone())
    .single_instance()
    .root::<View>("main")
    .run();
for link in links.drain() {
    // route `link.host`, `link.segments`, `link.query`
}

Acceptance

  1. A valid scheme://host/path?key=value parses into scheme, host, segments and query (parses_a_deep_link).
  2. Unknown schemes and traversal paths are dropped (rejects_an_unknown_scheme, rejects_a_traversal_path).
  3. Empty or malformed schemes are rejected before registration (rejects_an_empty_or_bad_scheme).
  4. Cloned AppLinks handles share one FIFO (clones_share_the_same_queue); App::deep_links stores that shared handle behind the services feature and the run path feeds initial and forwarded InstanceMessage arguments.
  5. auro::services re-exports the API surface (crates/auro/src/lib.rs).
  6. cargo fmt --all --check, cargo clippy --workspace --all-targets --locked -- -D warnings, cargo test --workspace --locked, and mdbook build docs pass.

Open questions

QuestionWhere it settles
Universal links / HTTPS associationsDeep-link follow-up
macOS bundle registration automationPackager follow-up
Unknown-origin consent policyDeep-link UX spec