System Concept

Sorane (็ฉบ้Ÿณ) is an Open Source Reference Implementation for a data delivery infrastructure that combines "Precision Typography" with "Post-Quantum Cryptography (PQC)". It is not intended as a finished product but as a "Technical Blueprint" to solve implementation challenges when public institutions issue Verifiable Credentials (VCs).

The two core pillars:

  1. Typography-First (Zero Layout Shift):
    • Analyzes the characters used on each page, then subsets and embeds fonts on-the-fly to ensure "pixel-perfect" rendering on any device.
    • Native support for IVS variation sequences and administrative external characters.
  2. Cryptographic Authenticity & Privacy:
    • All official documents are signed with hybrid signatures including Post-Quantum Cryptography (ML-DSA-44).
    • Supports Selective Disclosure (SD-CWT) to realize minimal data presentation with privacy in mind.
    • Adopts an authentication model similar to "Organizational Evidence" (e-Seals).

Directory Structure

srn/
โ”œโ”€โ”€ shared/           # Shared assets (fonts, schemas, base CSS)
โ”œโ”€โ”€ sites/            # Multi-tenant site source
โ”‚   โ””โ”€โ”€ srn/
โ”‚       โ”œโ”€โ”€ config.yaml
โ”‚       โ”œโ”€โ”€ content/      # Markdown files (*.md)
โ”‚       โ””โ”€โ”€ static/       # Static assets (images, css, pdf)
โ”œโ”€โ”€ dist/srn/         # Generated output (git-ignored)
โ”œโ”€โ”€ src/              # Source code
โ”‚   โ”œโ”€โ”€ core/         # Crypto, VC, font engine, shared utils
โ”‚   โ”œโ”€โ”€ ssg/          # Build pipeline, layouts, identity manager
โ”‚   โ”œโ”€โ”€ form/         # Web/A Form runtime
โ”‚   โ””โ”€โ”€ bin/          # CLI entrypoints
โ””โ”€โ”€ tests/            # Integration and unit tests

Getting Started

Prerequisites

  • Bun: Runtime environment (v1.0+).
  • Node.js: For compatibility (if needed).

Installation

git clone https://github.com/masanork/srn.git
cd srn
bun install

Initial Setup

No complex database setup is required. Proprietary fonts are ignored by git. Place your .ttf or .otf files in shared/fonts/. The build process will automatically analyze and subset fonts per page.

Building the Site

# Standard Build (Incremental)
bun run build

# Clean Build (Rebuild all)
bun run build -- --clean

Local Development

To preview the site locally:

# Build SRN site
bun run build:srn

# Serve dist directory
bun x http-server dist/srn

Key Features & How-to

1. Writing Content

Create Markdown files in sites/srn/content/.

---
title: "My Article"
layout: article
font: ipamjm.ttf
---
Content goes here.

2. Web/A Documents (Archive-Quality Web)

Use layout: weba for archival-grade Web/A documents. Standard layout: article pages are also signed as Web/A documents by default.

---
title: "Whitepaper"
layout: article
author: "Author Name"
---
  • Architecture: Implements HMP (Human-Machine Parity). Signs a JSON-LD payload that is cryptographically bound to the HTML content view.
  • Verification: Includes a "Web/A Signed" badge with download link for the credential.

3. Web/A Forms (Interactive Documents)

To create a verifiable interactive form, use layout: form.

---
title: "Application Form"
layout: form
---
- [text:name (placeholder="Your Name")] Name
- [number:age] Age
  • Single-File Runtime: Generates a self-contained HTML file incorporating all logic, CSS, and structural signatures.
  • Layer 2 Encryption (L2E): You can encrypt user inputs for specific recipients (issuers/aggregators).
  • Form Maker: Use the Web/A Form Maker to visually design forms.

3.1 CLI Usage for Forms

Manual form generation or batch processing:

bun src/form/cli.ts input.md > output.html

3.2 L2 Encryption Configuration

Add the following to your Markdown frontmatter to enable confidentiality:

l2_encrypt: true
l2_recipient_kid: "issuer#kem-2025"
l2_recipient_x25519: "<base64url>"
# l2_recipient_pqc: "<base64url>" # Optional ML-KEM-768 key
l2_encrypt_default: true

4. Font System (Typography)

SRN allows precise control over font stacking and glyph substitution.

  • Inline Glyph: [font_name:glyph_id] (e.g., [ipamjm:MJ000001]) embeds a specific glyph as SVG from the specified font.
  • Auto Lookup: Native characters and IVS sequences are automatically detected and subsetted.

5. AI-Assisted Migration (Excel to Form)

Sorane supports a semi-automated workflow to digitize legacy Excel forms:

  1. Extract: Convert Excel to Markdown using tools like markitdown.
  2. Map: Use the Migration Prompts to map entries to Web/A syntax.
  3. Generate: Refine the Markdown and generate the HTML via CLI.

6. Verification Tools (CLI & AI)

Sorane provides multiple ways to verify Web/A and VC documents without a browser.

CLI Validator

Verify documents directly from your terminal:

# Verify a local file with HMP check
bun run verify dist/srn/papers/web-a.ja.html --hmp --did dist/srn/did.json

# Verify a remote URL
bun run verify https://example.com/doc.html --hmp

MCP Server (AI Integration)

Integrate verification into AI models (like Claude or Gemini) via the Model Context Protocol:

# Start the MCP server
bun run mcp

Configure your MCP client to use bun run src/mcp-server.ts to enable verify_weba tools for your AI assistant.

6. Trust Management (Advanced)

  • Root Key: Generated automatically on first build in sites/srn/data/root-key.json. Back up this file to maintain issuer identity!
  • Revocation: Status lists are generated in dist/status-list.json.

7. Security Hardening & Auditability

Sorane implements several measures to ensure high-security requirements for public institutions:

  • Dependency Vendoring: To eliminate supply chain risks, core cryptographic libraries (@noble/*) are vendored into src/vendor/. No external registry access is required for core crypto logic during runtime.
  • SBOM/CBOM: A Software Bill of Materials (SBOM) and Cryptography Bill of Materials (CBOM) is provided in sbom.json (CycloneDX format). This lists all components and explicitly details the cryptographic assets, algorithms (including PQC), and their operational readiness.
  • Persistent Replay Protection: For data aggregation workflows, both the CLI and Browser aggregators support persistent nonce tracking.
    • CLI: Use --replay-store path/to/store.json to persist nonces across restarts.
    • Browser: Automatically uses localStorage for zero-touch persistent replay protection.
  • Side-Channel & Traffic Analysis Resistance: Includes unified error handling for decryption and block-size padding (512-byte multiples) to mitigate information leakage.

8. Testing & Coverage

Use Bun's built-in coverage to monitor regression risk before major changes.

# Run full test suite with coverage
bun test --coverage
  • Output: Bun prints a per-file coverage table (functions/lines) to stdout.
  • Baseline Tracking: Record the summary (% funcs/lines) in your work logs or release notes when making security-sensitive changes.
  • Headless Notes: Tests that rely on WebAuthn or WASM may require the default Bun environment; keep versions aligned with package.json.

Troubleshooting

  • Missing Glyphs: Ensure the correct font files are in shared/fonts/ and specified in the frontmatter or config.yaml.
  • Build Errors: Check your Markdown syntax and configuration.
  • Signature Invalid: If sites/srn/data/root-key.json was deleted, all previous signatures become invalid (Trust on First Use reset).

Built with Bun and OpenType.js.