You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: README.md
+33-14Lines changed: 33 additions & 14 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -35,33 +35,52 @@ FDD adoption solves both infrastructure and data consumption bottlenecks. We bel
35
35
5.**Decentralized APIs**: Removes the massive root infrastructure cost of building API endpoints for institutions. Instead of building webhooks to support parallel and downstream industries (e.g. the mortgage industry needing bank statements, or colleges needing school records), institutions can simply issue a secure, verifiable `.fdd` file to the user.
36
36
37
37
## Tooling & Ecosystem Guide
38
-
The OpenFDD ecosystem provides a full suite of typescript/javascript libraries to securely compose, sign, view, and inherently interact with FDD files.
38
+
The OpenFDD ecosystem provides a full suite of JavaScript libraries to securely compose, sign, view, verify, and interact with FDD files.
39
39
40
-
### 1. Composing & Building (`node-fdd`)
41
-
To build an `.fdd` file from your backend, you pack your Cryptographic JSON, your Mutable JSON, and your HTML template securely into the unified `.fdd` document wrapper:
40
+
### 1. Identity & Key Generation (`node-fdd`)
41
+
Before issuing documents, generate your institutional Ed25519 keypair and host your public identity:
42
42
```bash
43
-
# Install the Official OpenFDD CLI globally
44
43
npm install -g @coreyburns/node-fdd
45
44
46
-
# Pack the payload securely into the FDD container
To seamlessly render `.fdd` containers natively on your own web-platform without requiring plugins, simply reference the native layout library via our global jsDelivr CDN inside your DOM. It evaluates the No-JS constraints, routes Ephemeral State actions securely, and renders the Document safely!
75
+
### 3. Parsing & Viewing (`fdd-js`)
76
+
Render `.fdd` containers in your webplatform. The library now automatically resolves the issuer's `did:web` identity and displays a cryptographic trust badge:
58
77
```html
59
-
<!--Hosted securely out of explicit version tags to prevent un-authorized layout breaking-->
For End-Users navigating to FDD files natively on their disk, the custom routing extension acts as a Security Shield. It intercepts raw text rendering to sandbox the format, gracefully bypasses restrictive OS bounds allowing direct file-system saves, and actively prunes malware requests!
83
+
For end-users opening `.fdd`files from disk. Acts as a Security Shield: sandboxes rendering, enables direct file-system saves, and strips malicious embedding vectors.
# The Formatted Data Document (.fdd) Specification v1.1
1
+
# The Formatted Data Document (.fdd) Specification v1.2
2
2
3
3
## 1. Architectural Philosophy
4
4
An `.fdd` file is a "Local-First" interactive container. It treats the browser as an OS, allowing for a zero-infrastructure application experience where the file *is* the state. A document should not be a static printed picture of data (like a PDF), but rather a structured data payload wrapped seamlessly in presentation logic, natively capable of persisting its own user-driven mutations.
5
5
6
6
## 2. File Structure & Anatomy
7
-
An `.fdd` file is structurally a Single-File Web App (SWA) bounded by an `<fdd-container>` wrapper. The document strictly enforces a **No-JS Security Model**. Authors are entirely forbidden from loading or executing native `<script>` logic.
7
+
An `.fdd` file is structurally a Single-File Web App (SWA) bounded by an `<fdd-container>` wrapper. The document strictly enforces a **No-JS Security Model**. Authors are forbidden from loading or executing native `<script>` logic with executable MIME types.
8
8
9
9
### 2.1 The Data Segregation Model
10
-
To allow for "Protected Data" alongside "Mutable Notes," FDD enforces a layered integrity architecture based on `id` routing:
10
+
To allow for "Protected Data" alongside "Mutable Notes," FDD enforces a layered integrity architecture:
To allow developers and AI models to build complex, reactive applications (like CRMs or banking dashboards) without violating the No-JS security constraints, OpenFDD relies on a standardized set of declarative HTML actions parsed natively by the `fdd.js` wrapper execution engine.
42
+
## 3. The did:web Identity & Trust Model
37
43
38
-
### 3.1 Template Data Binding
39
-
The presentation `<template>` is evaluated using lightweight mustache-syntax against the merged dictionaries of `#fdd-data` and `#user-notes`.
***Array Iteration:** Use `{{#each arrayName}}` to iterate over nested objects. Within an iterative loop, the parser natively routes the `{{@index}}` tag to identify the active object's array index natively.
44
+
### 3.1 Issuer Identity (did:web)
45
+
Every `.fdd` document identifies its issuer using the `did:web` DID method. The issuer hosts a public key at a well-known URL, and any viewer can automatically resolve it to verify the document's authenticity.
| ⚠️ Invalid | Document tampered or signature mismatch |
112
+
| ❓ Unresolved | DID endpoint unavailable |
113
+
114
+
The trust badge renders **non-blocking** — documents always display immediately.
115
+
116
+
## 4. The Declarative Action Framework
117
+
To allow developers to build complex, reactive applications without violating the No-JS security constraints, OpenFDD relies on standardized declarative HTML actions.
118
+
119
+
### 4.1 Template Data Binding
120
+
The `<template>` is evaluated using Mustache-syntax against the merged `#fdd-data` and `#user-notes` dictionaries.
42
121
43
122
```html
123
+
<!-- Property binding -->
124
+
<h1>{{accountBalance}}</h1>
125
+
126
+
<!-- Array iteration -->
44
127
{{#each contacts}}
45
128
<divclass="card">
46
129
<h2>{{name}}</h2>
@@ -49,49 +132,46 @@ The presentation `<template>` is evaluated using lightweight mustache-syntax aga
49
132
{{/each}}
50
133
```
51
134
52
-
### 3.2 State Mutations & Interactions
53
-
The parser intercepts standard DOM elements annotated with `fdd-target` attributes explicitly mapping back to the mutable `#user-notes` JSON block. (Mutations targeting `#fdd-data` will trigger native compilation warnings and fail silently during run-time execution to protect cryptographic signature thresholds).
54
-
55
-
***Auto-Save Inputs:** Appending the `autosave` attribute to an `<input>` or `<textarea>` maps real-time keystrokes securely back to the file state.
### 3.3 Ephemeral State & Conditional Routing (The UI-State)
63
-
To track complex "Transient View State" (like actively modifying a contact card or swapping pages) without routinely spamming the user's hard-drive, OpenFDD provides an ephemeral rendering router detached entirely from the persistent `#user-notes` schema: `ui-state`.
64
-
65
-
***Setting Active View State:**`<button fdd-action="set-ui" fdd-target="selectedTab" fdd-value="contacts">`
66
-
***Deep Contextual Rendering Layouts:** Use `fdd-match` to explicitly isolate deep layout injections strictly to the target UI route!
An `.fdd` file acts as its own state database. Updates to the DOM efficiently sync back to the originating `.fdd` file natively.
78
-
79
-
* **Primary Strategy (File System Access API):** The `.fdd` parser bounds interactive changes to an explicit file-handle write-lock approval prompt on initial layout bounds. If granted, mutable components actively rewrite the local file.
80
-
* **Universal Fallback (The Save Pattern):** Because native write-locks are routinely restricted (e.g., Linux sandbox environments / URI contexts), the FDD specification standardizes a uniform "Save Updates" interface overlay. When active edits mutate the DOM, a persistent prompt alerts the user without interfering in the UI layout. Committing the respective save actively leverages ambient location hooks to definitively default the internal OS download to actively match the originating `.fdd`'s explicit filename!
81
-
82
-
## 5. Security Model & The Hidden Ink Risk
83
-
Since executable scripts are stripped, interactions scale solely through CSS Pseudo Types (`:checked`, `:hover`) and the rigid Declarative Action framework documented above.
84
-
85
-
### 5.1 The "Hidden Ink" Presentation Risk
86
-
Because OpenFDD utilizes declarative CSS for structural templating, there inherently exists a layout spoofing vector (e.g., deliberately matching text properties to background bounds, or hiding blocks via `display: none` to actively conceal contractual obligations).
87
-
88
-
To heavily mitigate this vector, OpenFDD formally separates the **Integrity Layer** (`#fdd-data`) from the loosely defined **Presentation Layer** (`<template>`).
89
-
* Authoritative `.fdd` viewers **SHOULD** proactively implement accessibility contrast safeguards, OR securely expose a persistent "Raw Data Inspector" UI guaranteeing immediate visibility towards the un-styled, pristine JSON structure.
90
-
* **The Governing Principle:** Presentation is merely a convenience; the raw cryptographically signed `#fdd-data` layer asserts the absolute legal source of truth.
91
-
92
-
## 6. The Advocacy Roadmap
93
-
To establish `.fdd` ubiquity across browsers and SaaS ecosystems:
94
-
1. **The "Trust Tier" Proposal:** Lobby W3C/WICG to explicitly configure Zero-JS containers securely to bypass the rampant "Permission Fatigue" common among local-first web app strategies.
95
-
2. **The "AI Grounding" Certification:** Forcefully position `.fdd` outputs as the prime injection metric for generative LLMs structure mapping, aggressively supplanting hallucinatory OCR-bound PDF scrapes with cryptographically pristine JSON-LD payloads.
96
-
3. **SaaS "Off-Ramp" Continuity:** Persuade leading core Enterprise architectures (Hubspot/Salesforce) to route client exports into highly interactive `.fdd` single-file-apps rather than static, un-recyclable PDF forms.
97
-
4. **The Safe Universal Reader:** Systematically deploy a highly accessible PWA handler catching default OS interactions while strategically routing telemtry insights towards browser vendor implementations natively.
135
+
### 4.2 State Mutations & Interactions
136
+
The parser intercepts DOM elements annotated with `fdd-*` attributes that map to the mutable `#user-notes` block. Mutations targeting `#fdd-data` (the signed block) will trigger compiler warnings and fail silently at runtime.
<!-- Renders ONLY when selectedTab === "contacts" -->
151
+
</div>
152
+
```
153
+
154
+
Conditional rendering:
155
+
-`<span fdd-if="{{isVerified}}">Certified</span>`
156
+
-`<span fdd-unless="{{archived}}">Active</span>`
157
+
158
+
## 5. The Self-Saving Persistence Mechanism
159
+
-**Primary (File System Access API):** The parser requests a write-lock on first interaction. If granted, mutations auto-sync to the local file.
160
+
-**Fallback (Save Banner):** A persistent "Save Updates" overlay downloads the updated `.fdd` file matching the original filename when the API is unavailable.
161
+
162
+
## 6. Security Model
163
+
164
+
### 6.1 Zero-Trust Embedding Policy
165
+
The compiler (`fdd-pack`) **fatally rejects** templates containing: `<script>`, `<iframe>`, `<object>`, `<embed>`, `<applet>`. The runtime parsers (`fdd-js`, `content.js`) additionally scrub any such elements from the Declarative Shadow DOM before rendering.
166
+
167
+
### 6.2 The "Hidden Ink" Presentation Risk
168
+
CSS can be used to visually conceal content (e.g., matching foreground to background colors). Authoritative viewers **SHOULD** implement a "Raw Data Inspector" that exposes the unstyled `#fdd-data` JSON — the cryptographically signed block is the **legal source of truth**, not the visual presentation.
169
+
170
+
### 6.3 The Private Key Boundary
171
+
The private key **never** leaves the issuer's server. The public key is always available via the `did:web` endpoint for open verification. A bad actor cannot forge a document without compromising the issuer's actual web domain.
172
+
173
+
## 7. The Advocacy Roadmap
174
+
1.**The "Trust Tier" Proposal:** Lobby W3C/WICG to configure Zero-JS containers as high-trust sandboxes, reducing "Permission Fatigue" for local-first web apps.
175
+
2.**AI Grounding:** Position `.fdd` as the canonical input format for LLMs — cryptographically pristine JSON-LD beats hallucinatory OCR-bound PDF scrapes.
176
+
3.**SaaS Off-Ramp:** Persuade Hubspot, Salesforce, and similar platforms to export to `.fdd` instead of static PDFs.
177
+
4.**Native Browser Support:** Systematically campaign for `.fdd` to be treated as a first-class file type alongside `.pdf` in Chrome, Firefox, and Safari.
0 commit comments