use std::fmt;
use std::sync::OnceLock;
use anyhow::{Context, Result, bail};
use rand_core::{OsRng, RngCore};
use zeroize::Zeroizing;
use super::PAIR_PORT;
const WORD_LIST: &str = include_str!("words.txt");
const WORD_COUNT: usize = 2048;
pub const CODE_WORDS: usize = 4;
const SECRET_LEN: usize = 16;
const INVITE_PREFIX: &str = "sb-pair:";
const PREFIX_LEN: usize = 4;
fn words() -> &'static [&'static str] {
static WORDS: OnceLock<Vec<&'static str>> = OnceLock::new();
WORDS.get_or_init(|| WORD_LIST.lines().collect())
}
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum CodeKind {
Words,
Invite,
}
impl CodeKind {
pub(super) fn byte(self) -> u8 {
match self {
Self::Words => 1,
Self::Invite => 2,
}
}
pub(super) fn from_byte(byte: u8) -> Option<Self> {
match byte {
1 => Some(Self::Words),
2 => Some(Self::Invite),
_ => None,
}
}
}
pub struct HostSecrets {
words: Zeroizing<[u16; CODE_WORDS]>,
secret: Zeroizing<[u8; SECRET_LEN]>,
}
impl fmt::Debug for HostSecrets {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
f.write_str("HostSecrets(..)")
}
}
impl HostSecrets {
pub fn generate() -> Self {
let mut words = Zeroizing::new([0u16; CODE_WORDS]);
for word in words.iter_mut() {
*word = u16::try_from(OsRng.next_u32() % WORD_COUNT as u32).unwrap_or(0);
}
let mut secret = Zeroizing::new([0u8; SECRET_LEN]);
OsRng.fill_bytes(secret.as_mut());
Self { words, secret }
}
pub fn code(&self) -> Zeroizing<String> {
let list = words();
Zeroizing::new(
self.words
.iter()
.map(|&i| list[usize::from(i)])
.collect::<Vec<_>>()
.join("-"),
)
}
pub fn invite(&self, hosts: &[String], port: u16) -> Zeroizing<String> {
let secret: String = self.secret.iter().map(|b| format!("{b:02x}")).collect();
let secret = Zeroizing::new(secret);
Zeroizing::new(format!(
"{INVITE_PREFIX}{}@{}:{port}",
secret.as_str(),
hosts.join(",")
))
}
pub(super) fn password(&self, kind: CodeKind) -> Zeroizing<Vec<u8>> {
match kind {
CodeKind::Words => words_password(&self.words),
CodeKind::Invite => secret_password(&self.secret),
}
}
}
fn words_password(indices: &[u16; CODE_WORDS]) -> Zeroizing<Vec<u8>> {
let mut out = Zeroizing::new(b"words:".to_vec());
for index in indices {
out.extend_from_slice(&index.to_be_bytes());
}
out
}
fn secret_password(secret: &[u8; SECRET_LEN]) -> Zeroizing<Vec<u8>> {
let mut out = Zeroizing::new(b"invite:".to_vec());
out.extend_from_slice(secret);
out
}
pub struct JoinCode {
kind: CodeKind,
password: Zeroizing<Vec<u8>>,
hosts: Vec<String>,
port: Option<u16>,
}
impl fmt::Debug for JoinCode {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
f.debug_struct("JoinCode")
.field("kind", &self.kind)
.field("hosts", &self.hosts)
.field("port", &self.port)
.finish_non_exhaustive()
}
}
impl JoinCode {
pub fn parse(text: &str) -> Result<Self> {
let text = text.trim();
if let Some(rest) = text.strip_prefix(INVITE_PREFIX) {
return parse_invite(rest);
}
let tokens: Vec<String> = text
.split(|c: char| c == '-' || c.is_whitespace())
.filter(|t| !t.is_empty())
.map(str::to_ascii_lowercase)
.collect();
if tokens.len() != CODE_WORDS {
bail!(
"a pairing code is {CODE_WORDS} words, like the one `sb pair` shows on the other \
device"
);
}
let mut indices = Zeroizing::new([0u16; CODE_WORDS]);
for (slot, token) in indices.iter_mut().zip(&tokens) {
*slot = word_index(token)
.with_context(|| format!("{token:?} is not a word `sb pair` uses"))?;
}
let mut tokens = tokens;
tokens.iter_mut().for_each(|t| zeroize::Zeroize::zeroize(t));
Ok(Self {
kind: CodeKind::Words,
password: words_password(&indices),
hosts: Vec::new(),
port: None,
})
}
pub fn kind(&self) -> CodeKind {
self.kind
}
pub fn hosts(&self) -> &[String] {
&self.hosts
}
pub fn port(&self) -> Option<u16> {
self.port
}
pub fn addresses(&self, host: Option<&str>) -> Result<Vec<(String, u16)>> {
if let Some(host) = host {
return Ok(vec![pairing_address(host)?]);
}
let port = self.port.unwrap_or(PAIR_PORT);
Ok(self.hosts.iter().map(|h| (h.clone(), port)).collect())
}
pub(super) fn password(&self) -> &[u8] {
&self.password
}
}
fn word_index(token: &str) -> Option<u16> {
let list = words();
let position = match list.binary_search(&token) {
Ok(i) => i,
Err(_) if token.len() >= PREFIX_LEN => {
list.iter().position(|word| word.starts_with(token))?
}
Err(_) => return None,
};
u16::try_from(position).ok()
}
fn parse_invite(rest: &str) -> Result<JoinCode> {
let malformed = || {
anyhow::anyhow!(
"a pairing invite reads sb-pair:<secret>@<hosts>:<port>; this one is cut short"
)
};
let (secret, place) = rest.split_once('@').ok_or_else(malformed)?;
let (hosts, port) = place.rsplit_once(':').ok_or_else(malformed)?;
let port: u16 = port.parse().map_err(|_| malformed())?;
if secret.len() != SECRET_LEN * 2 {
return Err(malformed());
}
let mut bytes = Zeroizing::new([0u8; SECRET_LEN]);
for (byte, pair) in bytes.iter_mut().zip(secret.as_bytes().chunks_exact(2)) {
let digits = std::str::from_utf8(pair).map_err(|_| malformed())?;
*byte = u8::from_str_radix(digits, 16).map_err(|_| malformed())?;
}
let hosts: Vec<String> = hosts
.split(',')
.filter(|h| !h.is_empty())
.map(str::to_string)
.collect();
if hosts.is_empty() {
return Err(malformed());
}
Ok(JoinCode {
kind: CodeKind::Invite,
password: secret_password(&bytes),
hosts,
port: Some(port),
})
}
pub fn pairing_address(host: &str) -> Result<(String, u16)> {
let host = host.trim();
let host = host.rsplit_once('@').map_or(host, |(_, h)| h);
if let Some(rest) = host.strip_prefix('[') {
let (name, after) = rest
.split_once(']')
.with_context(|| format!("{host:?} opens a bracket it does not close"))?;
let port = match after.strip_prefix(':') {
Some(port) => port
.parse()
.with_context(|| format!("{port:?} is not a port"))?,
None if after.is_empty() => PAIR_PORT,
None => bail!("{host:?} has text after its closing bracket"),
};
return Ok((name.to_string(), port));
}
match host.split_once(':') {
Some((name, port)) if !port.contains(':') => Ok((
name.to_string(),
port.parse()
.with_context(|| format!("{port:?} is not a port"))?,
)),
Some(_) => Ok((host.to_string(), PAIR_PORT)),
None if host.is_empty() => bail!("--host needs a host name or address"),
None => Ok((host.to_string(), PAIR_PORT)),
}
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn the_word_list_has_2048_sorted_words_with_distinct_prefixes() {
let list = words();
assert_eq!(list.len(), WORD_COUNT);
assert!(
list.windows(2).all(|w| w[0] < w[1]),
"binary search needs order"
);
let prefixes: std::collections::BTreeSet<&str> =
list.iter().map(|w| &w[..w.len().min(PREFIX_LEN)]).collect();
assert_eq!(prefixes.len(), WORD_COUNT);
assert!(
list.iter()
.all(|w| w.bytes().all(|b| b.is_ascii_lowercase()))
);
}
#[test]
fn a_shown_code_parses_back_to_the_same_password_in_any_spelling() {
let host = HostSecrets::generate();
let code = host.code();
let words: Vec<&str> = code.split('-').collect();
assert_eq!(words.len(), CODE_WORDS);
let spellings = [
code.to_string(),
code.to_uppercase(),
words.join(" "),
words
.iter()
.map(|w| &w[..w.len().min(PREFIX_LEN)])
.collect::<Vec<_>>()
.join(" "),
];
for spelling in spellings {
let parsed = JoinCode::parse(&spelling).unwrap();
assert_eq!(parsed.kind(), CodeKind::Words);
assert_eq!(parsed.password(), &host.password(CodeKind::Words)[..]);
}
}
#[test]
fn an_invite_parses_back_to_its_secret_hosts_and_port() {
let host = HostSecrets::generate();
let hosts = vec!["192.0.2.4".to_string(), "desk".to_string()];
let invite = host.invite(&hosts, 7301);
let parsed = JoinCode::parse(&invite).unwrap();
assert_eq!(parsed.kind(), CodeKind::Invite);
assert_eq!(parsed.hosts(), &hosts[..]);
assert_eq!(parsed.port(), Some(7301));
assert_eq!(parsed.password(), &host.password(CodeKind::Invite)[..]);
assert_ne!(
host.password(CodeKind::Invite),
host.password(CodeKind::Words)
);
}
#[test]
fn malformed_codes_are_refused() {
for bad in [
"",
"abandon ability able",
"abandon ability able about above",
"abandon ability able zzzz",
"aban-abil-able-ab",
"sb-pair:00@desk:1",
"sb-pair:00112233445566778899aabbccddeeff@:7201",
"sb-pair:00112233445566778899aabbccddeeff@desk",
"sb-pair:0011223344556677889gaabbccddeeff@desk:7201",
] {
assert!(JoinCode::parse(bad).is_err(), "{bad:?} must be refused");
}
}
fn secrets(words: [u16; CODE_WORDS], secret: [u8; SECRET_LEN]) -> HostSecrets {
HostSecrets {
words: Zeroizing::new(words),
secret: Zeroizing::new(secret),
}
}
fn tokens(text: &str) -> std::collections::BTreeSet<String> {
text.split(|c: char| !c.is_ascii_alphanumeric())
.filter(|t| !t.is_empty())
.map(str::to_ascii_lowercase)
.collect()
}
fn debug_views(host: &HostSecrets) -> [String; 3] {
let invite = host.invite(&["desk".into()], 7201);
[
format!("{host:?}"),
format!("{:?}", JoinCode::parse(&host.code()).unwrap()),
format!("{:?}", JoinCode::parse(&invite).unwrap()),
]
}
#[test]
fn secrets_never_appear_in_debug_output() {
let fixed = ["zebra", "orbit", "velvet", "lunar"];
let indices = fixed.map(|w| word_index(w).unwrap());
let secret: [u8; SECRET_LEN] = std::array::from_fn(|i| 0xa0 + i as u8);
let host = secrets(indices, secret);
let hex: String = secret.iter().map(|b| format!("{b:02x}")).collect();
let renderings = [
hex,
format!("{indices:?}"),
format!("{secret:?}"),
format!("{:?}", &host.password(CodeKind::Words)[..]),
format!("{:?}", &host.password(CodeKind::Invite)[..]),
];
for shown in debug_views(&host) {
let shown_tokens = tokens(&shown);
for word in fixed {
assert!(!shown_tokens.contains(word), "{word} in {shown}");
}
for rendering in &renderings {
assert!(
!shown.contains(rendering.as_str()),
"{rendering} in {shown}"
);
}
}
}
#[test]
fn debug_output_is_the_same_for_every_word_and_secret() {
let baseline = debug_views(&secrets([0; CODE_WORDS], [0; SECRET_LEN]));
for (index, word) in words().iter().enumerate() {
let byte = u8::try_from(index % 256).unwrap();
let host = secrets(
[u16::try_from(index).unwrap(); CODE_WORDS],
[byte; SECRET_LEN],
);
assert_eq!(debug_views(&host), baseline, "{word}");
}
}
#[test]
fn a_host_names_its_pairing_port_or_takes_the_default() {
let cases = [
("desk", ("desk", PAIR_PORT)),
("user@desk", ("desk", PAIR_PORT)),
("desk:7300", ("desk", 7300)),
("192.0.2.2:7300", ("192.0.2.2", 7300)),
("[fe80::1]", ("fe80::1", PAIR_PORT)),
("[fe80::1]:7300", ("fe80::1", 7300)),
("fe80::1", ("fe80::1", PAIR_PORT)),
];
for (input, (host, port)) in cases {
assert_eq!(
pairing_address(input).unwrap(),
(host.to_string(), port),
"{input}"
);
}
assert!(pairing_address("desk:port").is_err());
assert!(pairing_address("").is_err());
}
}