property_dossier 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 3bdbdbf29a19a497a1f8faca41696d5ef802a5bcee793b1b4e2e3d13a7763e52
+  data.tar.gz: 1b52bdb8bbb3137b7b5ac90af9f8e48cb0806fb2a9a6821a03e19f73c60dd6a6
+SHA512:
+  metadata.gz: 471c8fc2fb5f64b3965d8fbc416421dba39f8b0be6141431b0a5e70307a94a5a69e53499f172f72808eafccac2c9e82645a23d57f47b5a5ebcba502cd07aae1b
+  data.tar.gz: 8307f8b557e61766cff5b99900b5c4d3ad5ec53b5f7988e5217af571b0dce56aa1887efaf4a11f69f713f64d16940d9d0fd2fd801938b2b4b34fb191493b3976

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+# Changelog
+
+## 1.0.0
+
+First release: strict local manifest, revision-chain review, optional SHA-256 verification, explicit expiry checks and escaped standalone reports. No network or document-content interpretation.

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 NovAsia Estate
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,66 @@
+# Property Dossier
+
+An offline document-pack inspector for people handing property files from one team to another. It answers three concrete questions: **is a required file present and readable, have its bytes changed, and which revision is active?**
+
+It does not read the contents of a contract, establish legal title, authenticate a signature or decide which documents a jurisdiction requires. Your team supplies its own checklist. No uploads, telemetry, API key, paid account or runtime gems.
+
+## Five-minute example
+
+Ruby 3.1 or later:
+
+```sh
+gem install property_dossier
+property-dossier --manifest examples/manifest.json --root examples/documents --as-of 2026-11-06
+property-dossier --manifest examples/manifest.json --root examples/documents --as-of 2026-11-06 --format html > review.html
+```
+
+The example intentionally includes a missing inspection report. Exit 1 and `missing_requirement` are expected. All sample documents are invented plain-text fixtures, never client or legal documents. Download the [source examples](https://github.com/novasia-estate/property-dossier/tree/main/examples) or use those included in the installed gem directory (`gem which property_dossier`).
+
+For the library:
+
+```ruby
+require 'property_dossier'
+manifest = PropertyDossier::Manifest.load('manifest.json')
+report = PropertyDossier::Inspector.new(manifest, root: './documents', as_of: '2026-11-06').call
+puts report.to_json
+puts report.ok? # false if any error; warnings alone do not fail
+```
+
+## What an inspection catches
+
+* Required document kinds with no usable active document.
+* Missing, unreadable, empty or non-file paths.
+* SHA-256 mismatches when an expected digest is supplied.
+* Expired documents relative to an explicit date (expiry day itself is valid).
+* Unresolved competing revisions and broken supersession references.
+* Identical content under different names (warning).
+* Paths that escape the root, including resolved symbolic links.
+
+No automatic 'latest filename wins'. A readable replacement must explicitly supersede a lower revision of the same kind. A broken replacement is still reported and does not hide an otherwise usable prior file.
+
+## A practical handover
+
+1. Agree the required document kinds with the receiving professional.
+2. Copy the documents into a dedicated local folder you trust.
+3. Assign stable IDs, revisions and optional expiry dates in the manifest.
+4. Record digests at the point you actually receive a file.
+5. Run an inspection using a fixed date; resolve errors and review warnings.
+6. Transfer the manifest and files using your organisation's approved channel.
+7. Re-run at receipt. A matching digest establishes byte identity, not authenticity.
+
+The tool never edits source documents, silently refreshes expiry dates or infers a country's legal requirements. Output includes document paths: treat reports as sensitive if paths reveal client information.
+
+## Documentation
+
+* [Manifest contract](docs/manifest.md)
+* [Threat model and limits](docs/security.md)
+* [Integration and exit statuses](docs/integration.md)
+* [Changelog](CHANGELOG.md)
+
+Run `ruby -Ilib test/test_property_dossier.rb`. The suite uses temporary synthetic files and exercises invalid revisions, traversal, symlink escapes, expiry, tampering and HTML escaping. Build with `gem build property_dossier.gemspec`.
+
+## Maintainer
+
+Developed by [NovAsia Estate](https://novasia.estate/), a publisher of property guides and research for Cambodia, Thailand and Bali. This general-purpose tool contains no market offers, legal rules or regional tax assumptions.
+
+For the next JSON-schema validation step, see the separate [Property Schema Validator](https://github.com/novasia-estate/property-schema-validator). That tool checks records; this one checks a local document pack. MIT licensed. Reproducible bug reports without client files are welcome.

data/docs/integration.md

@@ -0,0 +1,7 @@
+# Integration
+
+CLI exit statuses: 0 = no errors; 1 = inspection completed with findings requiring review; 2 = invocation, manifest or root error. Warnings alone leave exit status 0. JSON includes schema version, explicit inspection date, property ID, original document metadata, computed hashes, usability and machine-readable finding codes.
+
+Redirect standard output to keep reports. Errors in invocation go to standard error. HTML is a standalone human-readable rendering of the same report. There is no automatic reporting upload.
+
+For CI, keep fixtures synthetic and run with a fixed date. An optional checksum is meaningful only if recorded through a trustworthy receipt process. To create one locally: `ruby -rdigest -e 'puts Digest::SHA256.file(ARGV[0]).hexdigest' path/to/file`.

data/docs/manifest.md

@@ -0,0 +1,11 @@
+# Manifest v1
+
+The manifest is UTF-8 JSON with `schema_version: 1`, a nonempty `property_id`, unique `requirements` document-kind strings and a `documents` array. Requirements are supplied by the user and are not a statutory checklist.
+
+Each document needs `id`, `kind`, forward-slash relative `path`, and positive integer `revision`. Optional fields: `sha256` (64 lowercase hexadecimal characters), `expires_on` (strict YYYY-MM-DD calendar date), `supersedes` (another document ID of the same kind with a lower revision). IDs and paths are unique. Unknown fields are retained in the report for your own descriptive metadata; do not put secrets there.
+
+Absolute paths, backslashes, drive letters, empty segments, `.` and `..` segments are rejected. The inspector resolves file paths and rejects escapes through symbolic links. Files should remain immutable while inspection runs.
+
+A supersession chain must increase revision numbers. This also prevents cycles. Multiple unrelated active documents of one kind produce an error even if revision numbers differ. Split document kinds when several distinct files are genuinely required (for example `floor_plan` and `site_plan`).
+
+Errors prevent a clean report. Duplicate bytes are warnings because a legitimate translation placeholder or duplicate receipt may need human review rather than automatic rejection. Dates are evaluated as calendar dates; the tool does not infer time zones or statutory grace periods.

data/docs/security.md

@@ -0,0 +1,7 @@
+# Security boundary
+
+Run only on a dedicated folder and manifest you are authorised to inspect. The program does not execute files, extract archives, parse PDFs, fetch URLs, send telemetry or modify documents. HTML reports escape text and include no external scripts or resources.
+
+File hashes attest only to bytes observed locally. A forged document can have a valid checksum. File existence, expiry metadata and a complete checklist do not establish legal validity, signer identity, ownership, availability or freedom from encumbrances.
+
+The root folder must not be changed by an untrusted concurrent process. Path resolution followed by file reading is not an operating-system sandbox and does not protect against hostile races. Special files are rejected; a large ordinary file may still take time to hash. Reports disclose names, manifest metadata and hashes; keep them under the same access controls as the pack. Do not upload client files in bug reports.

data/examples/documents/plan-fixture.txt

@@ -0,0 +1 @@
+SYNTHETIC TEST FILE. Example floor plan placeholder, no real address or measurements.

data/examples/documents/title-fixture.txt

@@ -0,0 +1 @@
+SYNTHETIC TEST FILE. Not a title deed, legal document or statement of ownership.

data/examples/manifest.json

@@ -0,0 +1,9 @@
+{
+  "schema_version": 1,
+  "property_id": "SYNTHETIC-UNIT-A12",
+  "requirements": ["title_copy", "floor_plan", "inspection_report"],
+  "documents": [
+    {"id": "title-v1", "kind": "title_copy", "path": "title-fixture.txt", "revision": 1},
+    {"id": "plan-v1", "kind": "floor_plan", "path": "plan-fixture.txt", "revision": 1}
+  ]
+}

data/exe/property-dossier

@@ -0,0 +1,25 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+require 'optparse'
+require_relative '../lib/property_dossier'
+options = { format: 'json' }
+parser = OptionParser.new do |p|
+  p.banner = 'Usage: property-dossier --manifest manifest.json --root ./documents --as-of YYYY-MM-DD [--format json|html]'
+  p.on('--manifest PATH') { |v| options[:manifest] = v }
+  p.on('--root PATH') { |v| options[:root] = v }
+  p.on('--as-of DATE') { |v| options[:as_of] = v }
+  p.on('--format FORMAT', %w[json html]) { |v| options[:format] = v }
+  p.on('--version') { puts PropertyDossier::VERSION; exit }
+  p.on('-h', '--help') { puts p; exit }
+end
+begin
+  parser.parse!
+  raise ArgumentError, 'unexpected positional arguments' unless ARGV.empty?
+  %i[manifest root as_of].each { |k| raise ArgumentError, "--#{k.to_s.tr('_', '-')} is required" unless options[k] }
+  report = PropertyDossier::Inspector.new(PropertyDossier::Manifest.load(options[:manifest]), root: options[:root], as_of: options[:as_of]).call
+  puts(options[:format] == 'html' ? report.to_html : report.to_json)
+  exit(report.ok? ? 0 : 1)
+rescue OptionParser::ParseError, ArgumentError, PropertyDossier::Manifest::Invalid, SystemCallError => e
+  warn "property-dossier: #{e.message}"
+  exit 2
+end

data/lib/property_dossier/inspector.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+module PropertyDossier
+  class Inspector
+    def initialize(manifest, root:, as_of:)
+      @manifest = manifest
+      @root = File.realpath(root)
+      raise ArgumentError, 'root must be a directory' unless File.directory?(@root)
+      @as_of = Date.iso8601(as_of)
+      @findings = []
+    end
+
+    def call
+      @findings = []
+      rows = @manifest.documents.map { |d| inspect_document(d) }
+      superseded = @manifest.documents.filter_map { |d| d['supersedes'] if rows.find { |r| r['id'] == d['id'] }['usable'] }
+      active = rows.select { |r| r['usable'] && !superseded.include?(r['id']) }
+      @manifest.requirements.each do |kind|
+        finding('missing_requirement', kind, 'No readable, current, checksum-valid active document satisfies this kind.') unless active.any? { |r| r['kind'] == kind }
+      end
+      active.group_by { |r| r['kind'] }.each do |kind, group|
+        finding('unresolved_versions', kind, 'Several active documents exist; explicitly supersede older versions.') if group.size > 1
+      end
+      rows.select { |r| r['actual_sha256'] }.group_by { |r| r['actual_sha256'] }.each_value do |group|
+        finding('duplicate_content', group.map { |r| r['id'] }.join(', '), 'Identical bytes are referenced more than once.', 'warning') if group.size > 1
+      end
+      Report.new(@manifest.property_id, @as_of.iso8601, rows, @findings)
+    end
+
+    private
+    def inspect_document(doc)
+      row = doc.merge('usable' => false)
+      path = File.join(@root, doc['path'])
+      unless File.exist?(path)
+        finding('missing_file', doc['id'], 'File does not exist.'); return row
+      end
+      resolved = File.realpath(path)
+      root_path = Pathname.new(@root)
+      relative = Pathname.new(resolved).relative_path_from(root_path).to_s
+      if relative == '..' || relative.start_with?("..#{File::SEPARATOR}") || Pathname.new(relative).absolute?
+        finding('outside_root', doc['id'], 'Resolved path escapes the dossier root.'); return row
+      end
+      unless File.file?(resolved)
+        finding('not_a_file', doc['id'], 'Path is not a regular file.'); return row
+      end
+      row['bytes'] = File.size(resolved)
+      row['actual_sha256'] = Digest::SHA256.file(resolved).hexdigest
+      valid = true
+      if row['bytes'].zero?
+        finding('empty_file', doc['id'], 'Empty documents do not satisfy requirements.'); valid = false
+      end
+      if doc['sha256'] && doc['sha256'] != row['actual_sha256']
+        finding('checksum_mismatch', doc['id'], 'Bytes differ from the manifest checksum.'); valid = false
+      end
+      if doc['expires_on'] && Date.iso8601(doc['expires_on']) < @as_of
+        finding('expired', doc['id'], 'Document expiry precedes the explicit inspection date.'); valid = false
+      end
+      row['usable'] = valid
+      row
+    rescue SystemCallError, ArgumentError => e
+      finding('unreadable', doc['id'], e.message); row
+    end
+
+    def finding(code, subject, message, severity = 'error')
+      @findings << { 'code' => code, 'subject' => subject, 'severity' => severity, 'message' => message }
+    end
+  end
+end

data/lib/property_dossier/manifest.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+module PropertyDossier
+  # Strict, portable manifest. File names refer to a local root, never remote URLs.
+  class Manifest
+    class Invalid < StandardError; end
+    attr_reader :property_id, :requirements, :documents
+
+    def self.load(path)
+      new(JSON.parse(File.read(path, encoding: 'UTF-8')))
+    rescue JSON::ParserError => e
+      raise Invalid, "Invalid JSON: #{e.message}"
+    end
+
+    def initialize(data)
+      fail!('manifest must be an object') unless data.is_a?(Hash)
+      fail!('schema_version must be 1') unless data['schema_version'] == 1
+      @property_id = text!(data['property_id'], 'property_id')
+      @requirements = data.fetch('requirements', [])
+      fail!('requirements must be unique strings') unless @requirements.is_a?(Array) && @requirements.all? { |r| r.is_a?(String) && !r.strip.empty? } && @requirements.uniq == @requirements
+      @documents = data['documents']
+      fail!('documents must be an array') unless @documents.is_a?(Array)
+      ids = []
+      paths = []
+      @documents.each do |d|
+        fail!('each document must be an object') unless d.is_a?(Hash)
+        id = text!(d['id'], 'document.id')
+        fail!("duplicate document id: #{id}") if ids.include?(id)
+        ids << id
+        text!(d['kind'], "#{id}.kind")
+        path = text!(d['path'], "#{id}.path")
+        fail!("unsafe path: #{path}") if path.include?('\\') || path.include?(':') || path.start_with?('/') || path.split('/').any? { |p| p.empty? || ['.', '..'].include?(p) }
+        fail!("duplicate document path: #{path}") if paths.include?(path)
+        paths << path
+        revision = d['revision']
+        fail!("#{id}.revision must be a positive integer") unless revision.is_a?(Integer) && revision.positive?
+        fail!("#{id}.sha256 must be lowercase hex") if d.key?('sha256') && !(d['sha256'].is_a?(String) && d['sha256'].match?(/\A[0-9a-f]{64}\z/))
+        fail!("#{id}.supersedes must reference a different document") if d.key?('supersedes') && (!d['supersedes'].is_a?(String) || d['supersedes'] == id)
+        next unless d.key?('expires_on')
+        value = d['expires_on']
+        begin
+          fail!("#{id}.expires_on must be YYYY-MM-DD") unless value.is_a?(String) && value.match?(/\A\d{4}-\d{2}-\d{2}\z/)
+          Date.iso8601(value)
+        rescue Date::Error
+          fail!("#{id}.expires_on is not a calendar date")
+        end
+      end
+      @documents.each do |d|
+        next unless d['supersedes']
+        prior = @documents.find { |p| p['id'] == d['supersedes'] }
+        fail!("unknown superseded document: #{d['supersedes']}") unless prior
+        fail!('supersession must preserve kind and increase revision') unless prior['kind'] == d['kind'] && prior['revision'] < d['revision']
+      end
+    end
+
+    private
+    def fail!(message)
+      raise Invalid, message
+    end
+    def text!(value, field)
+      fail!("#{field} must be nonempty text") unless value.is_a?(String) && !value.strip.empty?
+      value
+    end
+  end
+end

data/lib/property_dossier/report.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+require 'cgi'
+module PropertyDossier
+  class Report
+    attr_reader :data
+    def initialize(property_id, as_of, documents, findings)
+      @data = { 'schema_version' => 1, 'property_id' => property_id, 'as_of' => as_of,
+                'ok' => findings.none? { |f| f['severity'] == 'error' },
+                'documents' => documents, 'findings' => findings }
+    end
+    def ok? = @data['ok']
+    def to_json(*) = JSON.pretty_generate(@data)
+    def to_html
+      esc = ->(s) { CGI.escapeHTML(s.to_s) }
+      rows = @data['findings'].map { |f| '<tr>' + %w[severity code subject message].map { |k| "<td>#{esc.call(f[k])}</td>" }.join + '</tr>' }.join
+      "<!doctype html><html lang=\"en\"><meta charset=\"utf-8\"><title>Dossier inspection</title><style>body{font:16px system-ui;max-width:1100px;margin:3rem auto;padding:1rem}td,th{padding:.6rem;border:1px solid #ccc;text-align:left}table{border-collapse:collapse}code{overflow-wrap:anywhere}</style><h1>#{esc.call(@data['property_id'])}</h1><p>As of #{esc.call(@data['as_of'])}: #{ok? ? 'PASS' : 'REVIEW REQUIRED'}</p><p>File completeness and integrity only. This report does not authenticate documents or certify ownership.</p><table><tr><th>Severity</th><th>Code</th><th>Subject</th><th>Explanation</th></tr>#{rows}</table><h2>Machine-readable report</h2><pre><code>#{esc.call(to_json)}</code></pre></html>"
+    end
+  end
+end

data/lib/property_dossier/version.rb

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+module PropertyDossier
+  VERSION = '1.0.0'
+end

data/lib/property_dossier.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+require 'json'
+require 'date'
+require 'digest'
+require 'pathname'
+require_relative 'property_dossier/version'
+require_relative 'property_dossier/manifest'
+require_relative 'property_dossier/inspector'
+require_relative 'property_dossier/report'

metadata

@@ -0,0 +1,64 @@
+--- !ruby/object:Gem::Specification
+name: property_dossier
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- NovAsia Estate
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies: []
+description: Offline, dependency-free Ruby library and CLI. Explicit manifest requirements,
+  revision chains, expiry checks, SHA-256 verification and escaped HTML/JSON reports.
+  Does not authenticate documents or determine legal title.
+email:
+- info@novasia.estate
+executables:
+- property-dossier
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- docs/integration.md
+- docs/manifest.md
+- docs/security.md
+- examples/documents/plan-fixture.txt
+- examples/documents/title-fixture.txt
+- examples/manifest.json
+- exe/property-dossier
+- lib/property_dossier.rb
+- lib/property_dossier/inspector.rb
+- lib/property_dossier/manifest.rb
+- lib/property_dossier/report.rb
+- lib/property_dossier/version.rb
+homepage: https://novasia.estate/
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://novasia.estate/
+  source_code_uri: https://github.com/novasia-estate/property-dossier
+  bug_tracker_uri: https://github.com/novasia-estate/property-dossier/issues
+  documentation_uri: https://github.com/novasia-estate/property-dossier/blob/main/docs/manifest.md
+  changelog_uri: https://github.com/novasia-estate/property-dossier/blob/main/CHANGELOG.md
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.1'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: Inspect property document packs for completeness, conflicting revisions and
+  file integrity.
+test_files: []