flpdf-cli 0.10.0

Command-line tools for flpdf, mirroring qpdf inspection and rewrite subcommands.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
//! `flpdf rewrite --deterministic-id` CLI tests.
//!
//! Pins the wiring of qpdf's `--deterministic-id`:
//! - two runs over the same input are byte-identical (self-stable /ID);
//! - /ID[0] (permanent identifier) is preserved from the input, while /ID[1]
//!   (changing identifier) is content-derived and is not the `--static-id`
//!   constant;
//! - `--linearize` is supported: the deterministic /ID is derived from the
//!   linearized body and is self-stable across runs;
//! - `--static-id` takes precedence when combined with `--deterministic-id`,
//!   while any deterministic-id use remains incompatible with encryption;
//! - unlike `--static-id`, the flag is production-safe and emits no
//!   testing-only warning.
//!
//! The /ID[1] body-digest algorithm is verified by the library test
//! `writer::tests::deterministic_id_is_stable_and_equals_md5_over_body`. flpdf's
//! digest is its own scheme and is NOT byte-identical to qpdf's /ID (qpdf seeds a
//! second MD5 with the body digest plus the `/Info` strings), so no qpdf
//! `/ID`-equality oracle runs here; the `--deterministic-id` equivalence is
//! behavioural (deterministic, content-derived, permanent-ID-preserving).

use assert_cmd::Command as CargoCommand;
use predicates::prelude::*;
use std::path::{Path, PathBuf};
use tempfile::tempdir;

const COMPAT_FIXTURE_DIR: &str = "../../tests/fixtures/compat";

fn fixture_path(name: &str) -> PathBuf {
    Path::new(env!("CARGO_MANIFEST_DIR"))
        .join(COMPAT_FIXTURE_DIR)
        .join(name)
}

fn run_rewrite_det_id(input: &Path, output: &Path) {
    CargoCommand::cargo_bin("flpdf")
        .expect("flpdf binary")
        .args(["rewrite", "--deterministic-id"])
        .arg(input)
        .arg(output)
        .assert()
        .success();
}

/// Locate the last `/ID` array in a PDF and return its two hex-string element
/// payloads (without the angle brackets) — same shape handling as
/// `cli_static_id::extract_id_array`.
fn extract_id_array(pdf_bytes: &[u8]) -> (Vec<u8>, Vec<u8>) {
    let idx = pdf_bytes
        .windows(3)
        .enumerate()
        .filter(|(_, w)| *w == b"/ID")
        .map(|(i, _)| i)
        .next_back()
        .expect("/ID not found");
    let after = &pdf_bytes[idx + 3..];

    let open = after.iter().position(|&b| b == b'[').expect("expected [");
    let body = &after[open + 1..];

    let lt0 = body.iter().position(|&b| b == b'<').expect("expected <");
    let gt0 = body[lt0 + 1..]
        .iter()
        .position(|&b| b == b'>')
        .expect("expected >");
    let first = body[lt0 + 1..lt0 + 1 + gt0].to_vec();

    let rest = &body[lt0 + gt0 + 2..];
    let lt1 = rest.iter().position(|&b| b == b'<').expect("expected <");
    let gt1 = rest[lt1 + 1..]
        .iter()
        .position(|&b| b == b'>')
        .expect("expected >");
    let second = rest[lt1 + 1..lt1 + 1 + gt1].to_vec();

    (first, second)
}

#[test]
fn deterministic_id_is_stable_across_runs() {
    let tmp = tempdir().expect("tempdir");
    let input = fixture_path("one-page.pdf");
    let a = tmp.path().join("a.pdf");
    let b = tmp.path().join("b.pdf");

    run_rewrite_det_id(&input, &a);
    run_rewrite_det_id(&input, &b);

    assert_eq!(
        std::fs::read(&a).expect("read a"),
        std::fs::read(&b).expect("read b"),
        "two --deterministic-id runs must be byte-identical"
    );
}

#[test]
fn deterministic_id_preserves_permanent_id_and_is_content_dependent() {
    let tmp = tempdir().expect("tempdir");
    let out1 = tmp.path().join("one.pdf");
    let out2 = tmp.path().join("two.pdf");

    run_rewrite_det_id(&fixture_path("one-page.pdf"), &out1);
    run_rewrite_det_id(&fixture_path("two-page.pdf"), &out2);

    let (id0_1, id1_1) = extract_id_array(&std::fs::read(&out1).expect("read one"));
    let (_id0_2, id1_2) = extract_id_array(&std::fs::read(&out2).expect("read two"));

    // /ID[0] (permanent identifier) is preserved from one-page.pdf's input /ID.
    assert_eq!(
        id0_1.as_slice(),
        b"2dc780102304e5176780e8127fa6438c",
        "/ID[0] must be preserved from the source permanent identifier"
    );
    assert_ne!(
        id0_1, id1_1,
        "permanent and changing identifiers must differ"
    );
    // /ID[1] (changing identifier) is the content digest → content-dependent.
    assert_ne!(
        id1_1, id1_2,
        "different input content must yield a different /ID[1]"
    );
    assert_ne!(
        id1_1.as_slice(),
        b"31415926535897932384626433832795",
        "deterministic /ID[1] must not be the --static-id constant"
    );
}

#[test]
fn static_id_takes_precedence_over_deterministic_id_on_both_cli_surfaces() {
    let tmp = tempdir().expect("tempdir");
    let input = fixture_path("one-page.pdf");
    let rewrite_both = tmp.path().join("rewrite-both.pdf");
    let rewrite_static = tmp.path().join("rewrite-static.pdf");
    let top_level_both = tmp.path().join("top-level-both.pdf");
    let top_level_static = tmp.path().join("top-level-static.pdf");

    CargoCommand::cargo_bin("flpdf")
        .expect("flpdf binary")
        .args(["rewrite", "--deterministic-id", "--static-id"])
        .arg(&input)
        .arg(&rewrite_both)
        .assert()
        .success();
    CargoCommand::cargo_bin("flpdf")
        .expect("flpdf binary")
        .args(["rewrite", "--static-id"])
        .arg(&input)
        .arg(&rewrite_static)
        .assert()
        .success();
    assert_eq!(
        std::fs::read(&rewrite_both).expect("read rewrite both"),
        std::fs::read(&rewrite_static).expect("read rewrite static"),
        "rewrite --static-id must take precedence over --deterministic-id"
    );

    CargoCommand::cargo_bin("flpdf")
        .expect("flpdf binary")
        .args(["--deterministic-id", "--static-id"])
        .arg(&input)
        .arg(&top_level_both)
        .assert()
        .success();
    CargoCommand::cargo_bin("flpdf")
        .expect("flpdf binary")
        .arg("--static-id")
        .arg(&input)
        .arg(&top_level_static)
        .assert()
        .success();
    assert_eq!(
        std::fs::read(&top_level_both).expect("read top-level both"),
        std::fs::read(&top_level_static).expect("read top-level static"),
        "top-level --static-id must take precedence over --deterministic-id"
    );

    let rewrite_linearized_both = tmp.path().join("rewrite-linearized-both.pdf");
    let rewrite_linearized_static = tmp.path().join("rewrite-linearized-static.pdf");
    for (output, flags) in [
        (
            &rewrite_linearized_both,
            [
                "rewrite",
                "--linearize",
                "--deterministic-id",
                "--static-id",
            ]
            .as_slice(),
        ),
        (
            &rewrite_linearized_static,
            ["rewrite", "--linearize", "--static-id"].as_slice(),
        ),
    ] {
        CargoCommand::cargo_bin("flpdf")
            .expect("flpdf binary")
            .args(flags)
            .arg(&input)
            .arg(output)
            .assert()
            .success();
    }
    assert_eq!(
        std::fs::read(&rewrite_linearized_both).expect("read linearized both"),
        std::fs::read(&rewrite_linearized_static).expect("read linearized static"),
        "linearized --static-id must take precedence over --deterministic-id"
    );

    let top_level_objstm_both = tmp.path().join("top-level-objstm-both.pdf");
    let top_level_objstm_static = tmp.path().join("top-level-objstm-static.pdf");
    for (output, flags) in [
        (
            &top_level_objstm_both,
            [
                "--object-streams=generate",
                "--deterministic-id",
                "--static-id",
            ]
            .as_slice(),
        ),
        (
            &top_level_objstm_static,
            ["--object-streams=generate", "--static-id"].as_slice(),
        ),
    ] {
        CargoCommand::cargo_bin("flpdf")
            .expect("flpdf binary")
            .args(flags)
            .arg(&input)
            .arg(output)
            .assert()
            .success();
    }
    assert_eq!(
        std::fs::read(&top_level_objstm_both).expect("read object-stream both"),
        std::fs::read(&top_level_objstm_static).expect("read object-stream static"),
        "object-stream output must use static ID precedence"
    );
}

#[test]
fn deterministic_id_incompatible_with_encryption() {
    let tmp = tempdir().expect("tempdir");
    let input = fixture_path("one-page.pdf");
    let output = tmp.path().join("out.pdf");

    // Top-level alias path: `flpdf --deterministic-id --encrypt U O 256 -- IN OUT`.
    // The writer translates qpdf's generateID logic_error before any
    // encryption work happens.
    CargoCommand::cargo_bin("flpdf")
        .expect("flpdf binary")
        .args(["--deterministic-id", "--encrypt", "u", "o", "256", "--"])
        .arg(&input)
        .arg(&output)
        .assert()
        .failure()
        .stderr(predicate::str::contains(
            "INTERNAL ERROR: QPDFWriter::generateID has no data for deterministic ID",
        ));
}

#[test]
fn static_and_deterministic_id_remain_incompatible_with_encryption() {
    let tmp = tempdir().expect("tempdir");
    let input = fixture_path("one-page.pdf");
    let output = tmp.path().join("out.pdf");

    // With `--static-id`, qpdf's encryption setup generates the static `/ID`
    // successfully, so the failure comes from `pushMD5Pipeline`
    // (`QPDFWriter.cc:1011-1014`) rather than `generateID`:
    // `qpdf: Deterministic ID computation enabled after ID generation has
    // already occurred.` (exit 2), on both the plain and linearized routes.
    for extra in [&[][..], &["--linearize"][..]] {
        CargoCommand::cargo_bin("flpdf")
            .expect("flpdf binary")
            .args(["--static-id", "--deterministic-id"])
            .args(extra)
            .args(["--encrypt", "u", "o", "256", "--"])
            .arg(&input)
            .arg(&output)
            .assert()
            .failure()
            .code(2)
            .stderr(predicate::str::contains(
                "flpdf: Deterministic ID computation enabled after ID generation has already occurred.",
            ))
            .stderr(predicate::str::contains("generateID has no data").not());
    }
}

#[test]
fn deterministic_id_is_accepted_with_json() {
    // qpdf accepts this writer-only setting with JSON inspection. The
    // differential conflict matrix checks the complete qpdf output, while
    // this regression keeps the top-level parser from reintroducing the old
    // clap-only rejection.
    let input = fixture_path("one-page.pdf");

    CargoCommand::cargo_bin("flpdf")
        .expect("flpdf binary")
        .args(["--json", "--deterministic-id"])
        .arg(&input)
        .assert()
        .success()
        .stdout(predicate::str::contains("\"version\": 2"));
}

fn run_rewrite_linearize_det_id(input: &Path, output: &Path) {
    CargoCommand::cargo_bin("flpdf")
        .expect("flpdf binary")
        .args(["rewrite", "--linearize", "--deterministic-id"])
        .arg(input)
        .arg(output)
        .assert()
        .success();
}

#[test]
fn deterministic_id_with_linearize_is_stable_across_runs() {
    // qpdf computes a deterministic /ID for linearized output too; flpdf's
    // linearized writer derives it from an MD5 over the finished body and
    // back-patches every trailer / xref-stream /ID with the same value, so two
    // runs over the same input produce a byte-identical file.
    let tmp = tempdir().expect("tempdir");
    let input = fixture_path("one-page.pdf");
    let a = tmp.path().join("lin-a.pdf");
    let b = tmp.path().join("lin-b.pdf");

    run_rewrite_linearize_det_id(&input, &a);
    run_rewrite_linearize_det_id(&input, &b);

    let bytes_a = std::fs::read(&a).expect("read a");
    let bytes_b = std::fs::read(&b).expect("read b");
    assert_eq!(
        bytes_a, bytes_b,
        "two --linearize --deterministic-id runs must be byte-identical"
    );

    // The linearized output is a valid, linearized PDF with a non-placeholder /ID.
    assert!(
        bytes_a
            .windows(b"/Linearized".len())
            .any(|w| w == b"/Linearized"),
        "output must be linearized"
    );
    let (id0, id1) = extract_id_array(&bytes_a);
    assert_ne!(
        id0,
        vec![b'0'; 32],
        "/ID[0] placeholder must be patched to a real value"
    );
    assert_ne!(
        id1,
        vec![b'0'; 32],
        "/ID[1] placeholder must be patched to a real value"
    );
}

#[test]
fn deterministic_id_emits_no_testing_warning() {
    // Unlike --static-id, --deterministic-id is production-safe and must not
    // print the testing-only warning.
    let tmp = tempdir().expect("tempdir");
    let input = fixture_path("one-page.pdf");
    let output = tmp.path().join("out.pdf");

    CargoCommand::cargo_bin("flpdf")
        .expect("flpdf binary")
        .args(["rewrite", "--deterministic-id"])
        .arg(&input)
        .arg(&output)
        .assert()
        .success()
        .stderr(predicate::str::contains("testing only").not());
}

#[test]
fn deterministic_id_is_honored_in_page_ops_pipeline() {
    // The page-extraction pipeline rewrites through the full-rewrite writer, so
    // --deterministic-id must produce a stable /ID there too (not silently fall
    // back to a random one). Guards against a silent regression.
    let tmp = tempdir().expect("tempdir");
    let input = fixture_path("three-page.pdf");
    let a = tmp.path().join("a.pdf");
    let b = tmp.path().join("b.pdf");

    for out in [&a, &b] {
        CargoCommand::cargo_bin("flpdf")
            .expect("flpdf binary")
            .arg("--deterministic-id")
            .arg(&input)
            .args(["--pages", ".", "1-2", "--"])
            .arg(out)
            .assert()
            .success();
    }

    let (id0, id1) = extract_id_array(&std::fs::read(&a).expect("read a"));
    // three-page.pdf carries an input /ID, so /ID[0] (preserved) and /ID[1]
    // (content digest) differ.
    assert_ne!(id0, id1, "permanent /ID[0] and changing /ID[1] must differ");
    assert_eq!(
        std::fs::read(&a).expect("read a"),
        std::fs::read(&b).expect("read b"),
        "page-ops --deterministic-id must be byte-stable across runs"
    );
}

#[test]
fn deterministic_id_honored_in_split_pages() {
    // qpdf applies the deterministic-ID policy to every --split-pages output;
    // flpdf threads it into the chunk writer, so each chunk is byte-stable.
    let tmp = tempdir().expect("tempdir");
    let a = tmp.path().join("a");
    let b = tmp.path().join("b");
    std::fs::create_dir_all(&a).expect("mkdir a");
    std::fs::create_dir_all(&b).expect("mkdir b");
    let input = fixture_path("three-page.pdf");

    for dir in [&a, &b] {
        CargoCommand::cargo_bin("flpdf")
            .expect("flpdf binary")
            .arg("--deterministic-id")
            .arg(&input)
            .arg("--split-pages")
            .arg("--")
            .arg(dir.join("out.pdf"))
            .assert()
            .success();
    }

    assert_eq!(
        std::fs::read(a.join("out-1.pdf")).expect("chunk a"),
        std::fs::read(b.join("out-1.pdf")).expect("chunk b"),
        "split chunk must be byte-stable under --deterministic-id"
    );
}

#[test]
fn deterministic_id_honored_in_add_attachment() {
    // qpdf applies --deterministic-id to attachment writes too; flpdf threads it
    // into run_add_attachment, so the output is byte-stable across runs when the
    // attachment metadata is stable. qpdf generates a fresh current date when
    // these options are omitted, so explicit dates keep this test focused on
    // the deterministic-ID policy rather than the wall clock.
    let tmp = tempdir().expect("tempdir");
    let att = tmp.path().join("payload.txt");
    std::fs::write(&att, b"attachment payload").expect("write attachment");
    let input = fixture_path("three-page.pdf");
    let o1 = tmp.path().join("a.pdf");
    let o2 = tmp.path().join("b.pdf");

    for out in [&o1, &o2] {
        CargoCommand::cargo_bin("flpdf")
            .expect("flpdf binary")
            .arg("--deterministic-id")
            .arg("--add-attachment")
            .arg(&att)
            .args([
                "--creationdate=D:20240101120000Z",
                "--moddate=D:20240102130000Z",
            ])
            .arg("--")
            .arg(&input)
            .arg(out)
            .assert()
            .success();
    }

    assert_eq!(
        std::fs::read(&o1).expect("read a"),
        std::fs::read(&o2).expect("read b"),
        "add-attachment output must be byte-stable under --deterministic-id"
    );
}

#[test]
fn deterministic_id_accepted_with_check_like_qpdf() {
    // qpdf accepts `--check --deterministic-id` (the flag is moot for an
    // inspection that writes nothing — not an error). flpdf matches qpdf and
    // does NOT reject the combination.
    let input = fixture_path("one-page.pdf");
    CargoCommand::cargo_bin("flpdf")
        .expect("flpdf binary")
        .args(["--check", "--deterministic-id"])
        .arg(&input)
        .assert()
        .success();
}

#[test]
fn deterministic_id_top_level_alias_is_stable() {
    let tmp = tempdir().expect("tempdir");
    let input = fixture_path("one-page.pdf");
    let a = tmp.path().join("a.pdf");
    let b = tmp.path().join("b.pdf");

    for out in [&a, &b] {
        CargoCommand::cargo_bin("flpdf")
            .expect("flpdf binary")
            .arg("--deterministic-id")
            .arg(&input)
            .arg(out)
            .assert()
            .success();
    }

    assert_eq!(
        std::fs::read(&a).expect("read a"),
        std::fs::read(&b).expect("read b"),
        "two top-level --deterministic-id runs must be byte-identical"
    );
}