@broberg/legal 0.0.0-stage → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -1,3 +1,132 @@
1
- # Temporary Holding Version
1
+ # @broberg/legal
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ **Status: 0.2.0. Every document is a DRAFT (`draft: true`, rendered as «UDKAST») until the owner's lawyer has reviewed it (F110.3).**
4
+
5
+ One set of legal documents for every broberg.ai product: `terms`, `privacy`, `trust`, `dpa` and
6
+ `support`. The text is the same everywhere. Danish is the master and prevails; English sits beside it.
7
+ **components writes the text; each product fills in its OWN facts and shows the documents on its OWN
8
+ site.** legal.broberg.ai is an API, not a website: anything there that is not the API sends visitors
9
+ to broberg.ai.
10
+
11
+ ---
12
+
13
+ ## MUST: how a product shows its legal documents
14
+
15
+ Every product with a visible service shows these documents and never writes its own (owner decision
16
+ D-7effa0). This is a fixed onboarding step for every new project (the TERMS/GDPR card). Six steps:
17
+
18
+ ### 1. Write your product's facts, once, in YOUR repo
19
+
20
+ The texts have open slots (`facts` blocks) for what differs per product. You fill them with a
21
+ `ProductFacts` object kept in your own repo, for example `legal/facts.ts`:
22
+
23
+ ```ts
24
+ import type { ProductFacts } from "@broberg/legal";
25
+
26
+ export const FACTS: ProductFacts = {
27
+ id: "jam", // your product id: lower-case, stable
28
+ name: "Jam", // the name users know
29
+ hosting: [ // where data is stored and processed
30
+ { what: "Appen", where: "Stockholm, Sverige (EU)" },
31
+ { what: "Databasen", where: "Amsterdam, Holland (EU)" },
32
+ ],
33
+ dataCategories: [ // what personal data you hold
34
+ "Navn, e-mail og profilbillede fra login",
35
+ "Dit indhold, som du selv gemmer",
36
+ ],
37
+ subprocessors: [ // every vendor that touches personal data
38
+ { name: "Fly.io", purpose: "Drift af app og database", location: "Sverige og Holland", transfer: "Databehandleraftale med EU-standardkontrakter" },
39
+ ],
40
+ conversationAnalysis: true, // does the four-part conversation analysis apply?
41
+ healthData: false, // health data (GDPR art. 9)? physio apps: read docs/guides/health-data-physio.md
42
+ };
43
+ ```
44
+
45
+ - List only facts that are TRUE today. If you are unsure, leave it out and ask; never guess.
46
+ - Facts are data, never prose. Do not type a vendor name or an exception into the text. The package
47
+ turns your facts into tables and sentences through fixed templates.
48
+ - The facts change when your product changes (a new vendor, a new region). Update the file in the
49
+ same change.
50
+
51
+ ### 2. Get the texts: the npm package (recommended for JS/TS)
52
+
53
+ ```ts
54
+ import { getDocument, renderHtml } from "@broberg/legal"; // pin an exact version
55
+ import { FACTS } from "./legal/facts";
56
+
57
+ const doc = getDocument({ doc: "privacy", locale: "da", facts: FACTS });
58
+ doc.title; doc.version; doc.effectiveFrom; doc.draft; doc.contentHash;
59
+ renderHtml(doc); // semantic HTML with data-legal-id on every section and block; style it yourself
60
+ ```
61
+
62
+ The texts ship **inside** the package, so your site needs no network for them and cannot lose them
63
+ when legal.broberg.ai is down. New texts reach you as a new package version; components sends a
64
+ release report saying whether the wording changed.
65
+
66
+ ### 3. Or get them over HTTP (any stack)
67
+
68
+ ```
69
+ GET https://legal.broberg.ai/v1/documents → { documents: [{ doc, locale, version, effectiveFrom, draft, hash }] }
70
+ GET https://legal.broberg.ai/v1/{doc}.{da|en}.json → the template: sections with facts slots open, + version, draft, stale, hash
71
+ ```
72
+
73
+ Fill the slots with your facts: in JS/TS, `resolveTemplate(template, FACTS)` from this package. In
74
+ another language, render each `facts` block like this: `hosting` is a table (What | Where);
75
+ `dataCategories` is a list; `subprocessors` is a table (Vendor | Used for | Where | Transfer);
76
+ `conversationAnalysis` is one sentence saying whether your product is covered by the section on
77
+ conversation analysis. A missing English translation falls back to Danish; `stale: true` means the
78
+ English text is older than the Danish one, so show the Danish one or a notice.
79
+
80
+ ### 4. Cache: keep your own copy, and only fetch a new edition when there is one (HTTP route)
81
+
82
+ Your terms page must never go down because legal.broberg.ai is down or being updated.
83
+
84
+ 1. **Keep a snapshot in your repo or build** (`legal/snapshot/{doc}.{locale}.json`, the templates as
85
+ fetched). Your pages render from the snapshot. They never call the API on a page view.
86
+ 2. **Check for a new edition at most once a day:** `GET /v1/documents` and compare each `hash` with
87
+ your snapshot's. Same hash means there is nothing to do.
88
+ 3. **Only when a hash changed:** fetch that template, check it (it parses, `hash` matches the list,
89
+ `sections` is not empty), then replace the snapshot file in one step (write to a temp file, then
90
+ rename).
91
+ 4. **If anything fails** (timeout, 5xx, a check fails), keep the old snapshot, log it, and try again
92
+ tomorrow. Never empty a page because a fetch failed.
93
+ 5. Every answer carries an `ETag` and `cache-control: public, max-age=86400`. A request with
94
+ `If-None-Match: "<hash>"` answers an empty `304` when nothing changed.
95
+
96
+ The service runs cold: the first call after a quiet spell takes a second or two. That is fine for a
97
+ daily check and one more reason never to call it on a page view.
98
+
99
+ ### 5. Show the documents on YOUR site
100
+
101
+ - One page per document on your own domain, for example `/vilkaar`, `/privatliv`, `/tillid`.
102
+ `dpa` and `support` belong in customer contracts (Contract Manager fills `{customer.name}` and the
103
+ other placeholders); a public site shows `terms`, `privacy` and `trust`.
104
+ - Style and re-flow freely. **Never edit the text.**
105
+ - Show the version and the «gælder fra» date (`version`, `effectiveFrom`). While `draft` is true, show
106
+ the «UDKAST» marker (`renderHtml` does it for you).
107
+ - Link all of them in your footer. **Never link users to legal.broberg.ai**; it redirects to broberg.ai.
108
+
109
+ ### 6. Acceptance
110
+
111
+ Terms are accepted at sign-up with an **unticked** «Jeg accepterer vilkårene» checkbox; the privacy
112
+ policy is linked and shown, never "accepted". Store `{ doc, version, contentHash }` with the
113
+ acceptance, so "which text did they accept?" has an exact answer.
114
+
115
+ ---
116
+
117
+ ## Reference
118
+
119
+ - `getDocument({ doc, locale, facts })`: a finished document from the bundled templates plus your facts.
120
+ - `getTemplate({ doc, locale })`: the template, as the API serves it. `listDocuments()`: what `/v1/documents` serves.
121
+ - `resolveTemplate(template, facts)`: a finished document from a template you fetched. It gives the
122
+ same `contentHash` as `getDocument` with the same facts.
123
+ - `renderHtml(document)`: semantic HTML. `EXAMPLE_FACTS`: a filled-in example.
124
+ - **contentHash** = sha256 of the canonical JSON of the finished document; **hash** = the same for a template.
125
+ - **Placeholders** (`{customer.name}` and the rest) are a fixed list; an unknown one is refused.
126
+ - Zero dependencies (a built-in SHA-256, proven against FIPS vectors and node:crypto).
127
+
128
+ **0.2.0 (F110.14), breaking:** the fleet product registry and `library` are gone, and
129
+ `getDocument` takes `facts` instead of `product`. The per-product HTTP routes and the human pages are
130
+ gone too: legal.broberg.ai is an API.
131
+
132
+ Plan: `docs/features/F110-legal-documents.md`, `docs/features/F110.14-legal-is-an-api.md`.