Proof tokens — the newtype pattern

A clinker pipeline config is full of file paths: sources to read, outputs to write. A hostile or sloppy config could name ../../etc/passwd, or a path with a \0 byte, or a symlink that escapes its sandbox. Somewhere there must be a validator. The real question is harder: how does the engine guarantee that every path reaching the file loader went through that validator, with no chance some code path forgot to call it? Clinker’s answer turns “was this screened?” from a convention into a fact the compiler checks. The Rust tool underneath is the newtype, the smallest possible struct. It’s the same one-field-bundle shape you met building provenance records, but with its inner field kept private so the constructor is the only door in.

Prerequisites

• One reader, every format

→

Leads to

• Span-preserving parse & strictness

What you’ll be able to do

• Read the ValidatedPath newtype and name the two ingredients (a private inner field and a single constructor) that make it a proof token.
• Trace the chain SourceDb::load needs ValidatedPath → only validate_path makes one → so every loaded path was screened, and explain why a missing check becomes a compile error rather than a runtime hole.
• Write a small newtype whose privacy you can test: prove the forged constructor is rejected and the validated one is accepted.
• Distinguish “parse, don’t validate” (parse once into a stricter type) from “validate and pass the loose type onward”, and say which one carries proof in the type.

New terms in this lesson (each is also expanded inline at the point you first need it):

• newtype: a one-field struct that gives an existing type a new, distinct identity.
• proof token: a value you can only hold once a check has passed, so the type itself is the proof.
• type-state: encoding a state (screened / unscreened) into the type so the compiler tracks it.
• “parse, don’t validate”: parse a loose value once into a stricter type that can only exist when the check passed, instead of re-checking a loose type everywhere. Pre-taught where it appears below.

Predict first

✋ Predict first

ValidatedPath is declared as `pub struct ValidatedPath(PathBuf)`: a public struct, but the inner PathBuf has NO `pub` in front of it. Outside the security.rs module, can you write `ValidatedPath(some_path)` to build one by hand? Decide yes or no, and name what stops you, before revealing.

Decide on your answer before you open the reveal — committing a guess is what makes it stick.

Reveal the answer

No. Code outside the security.rs module cannot write ValidatedPath(some_path). The struct type is pub, so other modules can name it and hold one; but the inner field is private (no pub), so other modules cannot construct one through the tuple-struct syntax. The only doorway left open is the module’s public constructor, validate_path.

That asymmetry, public type and private field, is the entire mechanism. Possessing a ValidatedPath becomes a proof token: the only way to have one is to have gone through validate_path and gotten Ok.

The wrong mental model to drop: “pub struct means everything about it is public.” It does not. pub on the struct exposes the type; each field needs its own pub to be constructible or readable from outside. Leave the field bare and you have made the constructor the sole gate, on purpose.

A newtype is a struct around one value

A newtype is a struct that wraps a single existing type to give it a new identity:

clinker-plan ·security.rs ·ValidatedPath type @19acdcb4

#[derive(Debug, Clone, PartialEq, Eq, Hash)]
pub struct ValidatedPath(PathBuf);

A ValidatedPath is a PathBuf, but the type system treats it as distinct: you cannot pass a raw PathBuf where a ValidatedPath is wanted. The crucial detail is invisible at first glance: the inner field has no pub. It is private to the module. So nothing outside security.rs can write ValidatedPath(some_path) to conjure one. The only doorway in is the module’s constructor.

The single doorway: validate_path

There is exactly one public function that returns a ValidatedPath, and it does the screening before handing one back:

clinker-plan ·security.rs ·validate_path fn @19acdcb4

pub fn validate_path(
    raw: &Path,
    base_dir: &Path,
    allow_absolute: bool,
) -> Result<ValidatedPath, Diagnostic> {
    // rejects: null bytes; URL-encoded "%2e%2e" traversal; ".." components;
    // absolute / drive-anchored paths (unless allowed); then canonicalizes and
    // rejects anything that escapes base_dir via a symlink.
    // ...
    Ok(ValidatedPath(resolved))   // the ONE place a ValidatedPath is born
}

Read what that buys you. Because the field is private, the only way to hold a ValidatedPath is to have called validate_path and gotten Ok. So the type itself is a proof token: possessing one is compile-time evidence that the path was canonicalized, scoped to its base directory, and screened for traversal and null-byte attacks. The module doc names the pattern outright:

//! The only way to obtain a `ValidatedPath` is by calling `validate_path`.
//! The newtype's inner field is private, so downstream code that consumes a
//! `ValidatedPath` has compile-time proof that the path has been canonicalized,
//! scoped to its base directory, and screened for directory-traversal and
//! null-byte attacks.
//! This is the "token of proof" pattern.

The consumer demands the token

The payoff is at the file loader. SourceDb::load, the function that actually opens a file, does not take a PathBuf. It takes a ValidatedPath, by value:

clinker-plan ·span.rs ·SourceDb type @19acdcb4

crates/clinker-plan/src/span.rs

pub fn load(&mut self, path: ValidatedPath) -> std::io::Result<FileId> {
    // by the time we're here, the path is PROVEN screened — its type says so
}

Now trace the consequence. To call load, you need a ValidatedPath. To get a ValidatedPath, you must call validate_path. There is no other path through the type system. A programmer who forgets to validate doesn’t get a subtle runtime hole. They get a compile error, because they’re holding a PathBuf where a ValidatedPath is required. The class of bug “we loaded a file without screening its path” has been designed out of existence.

This is the essence of “parse, don’t validate”: instead of checking a value and then passing the same loose type onward (hoping every later reader re-checks or trusts it), you parse it once into a more specific type that can only exist when the check passed. The proof rides along in the type. Put another way, ValidatedPath is a type-state: the screened state of a path is a different type from a raw, unscreened one, so the compiler tracks “has this been checked?” for you, with no flag to read at runtime.

Worked → completion → faded

The module-privacy mechanism is small enough to hold in your hand. We build it up one rung at a time: read a complete worked version, fill a single gap, then write the whole thing.

Worked: forge one, and watch the compiler refuse

Here is the full pattern in miniature: a ValidatedPath newtype with a private inner field, its one constructor, and a load that demands the token. Run it, then uncomment the forged line and run again. The compiler will refuse.

rust // editable

reset ▶ run

mod security {
  // Private inner field: only this module can build one.
  #[derive(Debug)]
  pub struct ValidatedPath(String);

  impl ValidatedPath {
      pub fn as_str(&self) -> &str { &self.0 }
  }

  // The ONE constructor — screens the input first.
  pub fn validate_path(raw: &str) -> Result<ValidatedPath, String> {
      if raw.contains("..") {
          return Err(format!("rejected traversal: {raw}"));
      }
      Ok(ValidatedPath(raw.to_string()))
  }
}

// The loader demands proof: it cannot be called without a ValidatedPath.
fn load(path: &security::ValidatedPath) -> String {
  format!("opening {}", path.as_str())
}

fn main() {
  match security::validate_path("data/customers.csv") {
      Ok(vp) => println!("{}", load(&vp)),
      Err(e) => println!("{e}"),
  }
  match security::validate_path("../../etc/passwd") {
      Ok(vp) => println!("{}", load(&vp)),
      Err(e) => println!("{e}"),
  }

  // Try this: forge a token by hand, bypassing the validator.
  // let forged = security::ValidatedPath("../../etc/passwd".to_string());
  // println!("{}", load(&forged));
  // ^ won't compile: the tuple-struct field is private to the `security` module.
}

mod security { // Private inner field: only this module can build one. #[derive(Debug)] pub struct ValidatedPath(String); impl ValidatedPath { pub fn as_str(&self) -> &str { &self.0 } } // The ONE constructor — screens the input first. pub fn validate_path(raw: &str) -> Result<ValidatedPath, String> { if raw.contains("..") { return Err(format!("rejected traversal: {raw}")); } Ok(ValidatedPath(raw.to_string())) } } // The loader demands proof: it cannot be called without a ValidatedPath. fn load(path: &security::ValidatedPath) -> String { format!("opening {}", path.as_str()) } fn main() { match security::validate_path("data/customers.csv") { Ok(vp) => println!("{}", load(&vp)), Err(e) => println!("{e}"), } match security::validate_path("../../etc/passwd") { Ok(vp) => println!("{}", load(&vp)), Err(e) => println!("{e}"), } // Try this: forge a token by hand, bypassing the validator. // let forged = security::ValidatedPath("../../etc/passwd".to_string()); // println!("{}", load(&forged)); // ^ won't compile: the tuple-struct field is private to the `security` module. }

The first path loads, the second is rejected by the validator. And the commented forgery will not compile if you uncomment it, because the field is private to the security module. That refusal is the whole guarantee. In real clinker the same refusal is locked in by a compile_fail doctest that tries the forgery on purpose and asserts the compiler rejects it.

Completion: write the screening check

Same shape, one gap. The newtype, its privacy, the constructor’s signature, and load are all in place, but validate_path currently lets everything through. Complete the one guard so that a path containing .. is rejected with an Err, and only a clean path becomes a ValidatedPath. One new idea on this rung: the check lives inside the only doorway, so every token that exists has passed it.

rust // editable

reset ▶ run

mod security {
  #[derive(Debug)]
  pub struct ValidatedPath(String);

  impl ValidatedPath {
      pub fn as_str(&self) -> &str { &self.0 }
  }

  pub fn validate_path(raw: &str) -> Result<ValidatedPath, String> {
      // TODO: reject traversal — if `raw` contains "..", return an Err
      //       describing the rejection; otherwise fall through and build one.
      Ok(ValidatedPath(raw.to_string()))
  }
}

fn load(path: &security::ValidatedPath) -> String {
  format!("opening {}", path.as_str())
}

fn main() {
  for candidate in ["data/customers.csv", "../../etc/passwd"] {
      match security::validate_path(candidate) {
          Ok(vp) => println!("{}", load(&vp)),
          Err(e) => println!("{e}"),
      }
  }
}

mod security { #[derive(Debug)] pub struct ValidatedPath(String); impl ValidatedPath { pub fn as_str(&self) -> &str { &self.0 } } pub fn validate_path(raw: &str) -> Result<ValidatedPath, String> { // TODO: reject traversal — if `raw` contains "..", return an Err // describing the rejection; otherwise fall through and build one. Ok(ValidatedPath(raw.to_string())) } } fn load(path: &security::ValidatedPath) -> String { format!("opening {}", path.as_str()) } fn main() { for candidate in ["data/customers.csv", "../../etc/passwd"] { match security::validate_path(candidate) { Ok(vp) => println!("{}", load(&vp)), Err(e) => println!("{e}"), } } }

💡 Hint 1

The guard is a single if. str::contains answers “does this string contain that substring?”; return early with Err(...) when it does, before the Ok(...) line ever runs.

Show solution

pub fn validate_path(raw: &str) -> Result<ValidatedPath, String> {
    if raw.contains("..") {
        return Err(format!("rejected traversal: {raw}"));
    }
    Ok(ValidatedPath(raw.to_string()))
}

Because this is the only function that can build a ValidatedPath (the field is private), putting the check here means no ValidatedPath can exist without having passed it. That is the proof-token guarantee in one early-return.

Faded: build the whole token from a skeleton

Now write it yourself. A Port is a u16 that must be in the range 1024..=65535 (the non-privileged ports). Make a ValidPort newtype that can only hold a screened port, with a single constructor parse_port that rejects out-of-range values, and a bind function that demands the token. The skeleton names the pieces; you supply the bodies, and the privacy.

rust // editable

reset ▶ run

mod net {
  // TODO: a newtype around u16 with a PRIVATE inner field.
  //       (a public struct whose inner field has no `pub`)

  // TODO: the ONE constructor. Accept 1024..=65535; reject anything else
  //       with an Err(String). Return Result<ValidPort, String>.

  // TODO: a read accessor, e.g. `fn get(&self) -> u16`.
}

// `bind` demands proof: it takes a ValidPort, never a bare u16.
fn bind(port: &net::ValidPort) -> String {
  format!("listening on :{}", port.get())
}

fn main() {
  for candidate in [8080u16, 80, 65000] {
      match net::parse_port(candidate) {
          Ok(p) => println!("{}", bind(&p)),
          Err(e) => println!("rejected {candidate}: {e}"),
      }
  }
  // Try it: net::ValidPort(80) by hand — won't compile, field is private.
}

mod net { // TODO: a newtype around u16 with a PRIVATE inner field. // (a public struct whose inner field has no `pub`) // TODO: the ONE constructor. Accept 1024..=65535; reject anything else // with an Err(String). Return Result<ValidPort, String>. // TODO: a read accessor, e.g. `fn get(&self) -> u16`. } // `bind` demands proof: it takes a ValidPort, never a bare u16. fn bind(port: &net::ValidPort) -> String { format!("listening on :{}", port.get()) } fn main() { for candidate in [8080u16, 80, 65000] { match net::parse_port(candidate) { Ok(p) => println!("{}", bind(&p)), Err(e) => println!("rejected {candidate}: {e}"), } } // Try it: net::ValidPort(80) by hand — won't compile, field is private. }

Show solution

mod net {
    #[derive(Debug)]
    pub struct ValidPort(u16); // inner field private — the whole mechanism

    impl ValidPort {
        pub fn get(&self) -> u16 { self.0 }
    }

    pub fn parse_port(raw: u16) -> Result<ValidPort, String> {
        if (1024..=65535).contains(&raw) {
            Ok(ValidPort(raw))
        } else {
            Err(format!("port {raw} is outside 1024..=65535"))
        }
    }
}

8080 and 65000 bind; 80 is rejected because it is below 1024. The shape is identical to ValidatedPath: public type, private field, one screening constructor, a consumer that demands the token. Change the wrapped type and the check, and you have minted a new proof token. That is the reusable pattern.

Encapsulation is the load-bearing part

Strip away the security specifics and the reusable idea is this: a newtype is only a proof token if its inner value is private. A pub struct ValidatedPath(pub PathBuf) would prove nothing, since anyone could build one from any path. Privacy is what makes the constructor the sole gate, and the sole gate is what makes the type mean something. You’ll see the same shape in the next two lessons: Spanned<T> and CompiledPlan are both “you can only get one by going through the right door” types.

Comfortable with newtypes and the proof-token pattern? Skip ahead →

// quick check

Why can't a programmer accidentally call SourceDb::load with an unscreened path?

• load checks the path again internally before opening it
• load requires a ValidatedPath, and the only way to obtain one is validate_path (the inner field is private), so an unscreened path is a compile error
• A runtime assertion panics if the path wasn't validated

Retrieval checkpoint

✓ Checkpoint — proof tokens

💡 Hint 1

Look at the struct line: is there a pub before the inner type? Then look at validate_path’s return type and load’s parameter type. The two grep results bracket the only doorway.

What the greps establish

pub struct ValidatedPath(PathBuf): the inner field has no pub, so it is private to the module. validate_path is the only function returning ValidatedPath, and it screens first. The compile_fail doctest proves a hand-built ValidatedPath(...) does not compile outside the module. load takes ValidatedPath by value, so the loader can only be reached through the validator. The chain is airtight at compile time.

// quick check

What single change would destroy the security guarantee?

• Renaming validate_path to validate
• Making the inner field public (pub struct ValidatedPath(pub PathBuf)), since then anyone could construct one from an unscreened path
• Deriving Clone on ValidatedPath

// quick check

Which describes "parse, don't validate", and which is the MISCONCEPTION to correct?

• Parse the value once into a stricter type (ValidatedPath) that can only exist when the check passed, so later code never re-checks
• Validate the path, then keep passing the same PathBuf onward and trust that everyone downstream remembers it was already checked
• Skip validation entirely because the type system will catch bad paths on its own

// quick check

Spaced recall from Structs & provenance: ValidatedPath is declared `pub struct ValidatedPath(PathBuf)`. What kind of type is this, and how many fields does a value hold?

• An enum, where a value is exactly one of several variants
• A tuple struct (a one-field struct): every value bundles exactly that one field, and the field's own privacy is what gates construction
• A trait, which only declares method signatures and carries no data

You should be able to:

• You can explain why ValidatedPath's inner field is private and what would break if it were pub
• You can trace the chain: load needs ValidatedPath → only validate_path makes one → so every loaded path is screened
• You wrote a newtype (ValidPort) with a private field and a single screening constructor, and saw the forged constructor refuse to compile
• You can state what 'parse, don't validate' means in one sentence, and distinguish it from validate-then-pass-the-loose-type

Verify in the checkout:

grep -n 'pub struct ValidatedPath' crates/clinker-plan/src/security.rs
grep -n 'pub fn validate_path' crates/clinker-plan/src/security.rs
grep -n 'compile_fail' crates/clinker-plan/src/security.rs
grep -n 'fn load' crates/clinker-plan/src/span.rs

Connections

A private field turned a security check into a type. Next, Span-preserving parse, we’ll see the parser side of the same philosophy: how clinker funnels all YAML through one chokepoint and keeps the source location of every value, so a typo in a config points at the exact line that’s wrong.

Mark this lesson complete