GoogleCloudPlatform / GoogleCloudPlatform/knowledge-catalog
[OKF v0.1] Erasing a concept currently discloses it — an opt-in erasure conformance profile
- Dominant language
- TypeScript
- Stars
- 9.2k
- Forks
- 782
- Avg merge
- 6h 36m
- Merged PRs (30d)
- 85
Description
## The leak
In OKF the file path is the concept's identity, and consumption is permissive: a consumer must tolerate broken cross-links rather than reject the bundle. Those two rules combine into a privacy problem at deletion time. Remove a concept that carried or referenced personal data — say `tables/customers.md` — and every inbound link now dangles, but the bundle stays valid. The dangling target still spells out `tables/customers.md`. The deletion artifact is itself the disclosure: anyone reading the graph learns the erased concept's ID and that it once existed. `log.md` and git retain the prior content on top of that.
So today, deleting a concept is both lossy (no record of what was removed or why) and leaky (the absence names the thing). That blocks OKF wherever data-subject erasure applies — GDPR Art. 17, CPRA deletion — which is the same cross-org-exchange and metadata-as-code territory OKF is built for.
## What a format-level fix can and can't do (up front)
This proposal stays inside OKF's "format, not platform" line: markdown + frontmatter + a pointer, no SDK, no runtime. That bounds it, and the bounds are worth stating before the mechanism:
- **OKF can't make git forget.** History rewriting (`git filter-repo`) and erasing the underlying resource datastore stay the producer's responsibility. The in-format mechanism governs the working tree and ships a portable, checkable attestation that an authorized erasure happened — it is not the erasure of the source data itself.
- **The path is identity, so the path still leaks.** Replacing a concept in place removes the dangling-link disclosure, but the path string (`…/customers.md`) continues to name the former concept. Fully closing that needs opaque paths, which trade directly against OKF's human-readable ethos; this profile deliberately does not go there. The certificate (below, out of band) is where the claim about the actual data lives.
- **`log.md` travels with the bundle.** It's already reserved and append-only, so an erasure entry written there must itself contain no personal data or recoverable rendering — otherwise the fix just relocates the leak from the dangling link into the history file.
None of these is solved by hand-waving; they're the honest boundary of what a markdown-only convention can claim.
## Proposed delta (minimal, opt-in)
- **A conventional `Tombstone` type.** An erased concept is replaced in place — same concept ID / path — by a concept whose `type` is `Tombstone`. Preserving the path keeps the graph intact: inbound links resolve to a declared, uniform Tombstone instead of dangling, so absence is stated rather than inferred. This is proposed as a *convention over the open `type` field*, not a reserved type — OKF lists "defining a fixed taxonomy of concept types" as a non-goal, so it needs no spec-level type registry to adopt.
- **No recoverable content.** A Tombstone body MUST contain no personal data and no recoverable rendering of the erased concept. Frontmatter, all optional except `type`:
```yaml
type: Tombstone
erased: 2026-06-18T09:00:00Z # ISO 8601
erasure_reason: gdpr-art-17 # convention-tagged free string
certificate: https://…/cert/abc # resource link to an erasure certificate
commitment: # salted/keyed commitment to pre-erasure bytes
commitment_alg: HMAC-SHA256 # signals keyed, not a bare digest
```
- **Salted/keyed commitment, not a bare hash.** A holder of the original can verify the Tombstone corresponds to it, without a bare digest enabling brute-force confirmation of low-entropy personal values. Key custody is the producer's.
- **Base required fields, with non-disclosing values.** A Tombstone must still satisfy whatever fields the spec/tooling require of any concept (the reference parser enforces `type`, `title`, `description`, `timestamp`, beyond the one field the prose names). The profile rule: those values MUST NOT disclose the erased concept — e.g. `title: Erased concept`, a generic `description` — since a faithful title/description would itself leak what was removed. (Verified against the reference parser: a Tombstone omitting these is rejected; with non-disclosing values it passes and renders as a normal graph node.)
- **Audit travels with the bundle.** Erasure events append to the existing reserved `log.md` — subject to the no-PII rule above for the log entry itself.
- **Erasure-conformance (new optional profile).** A bundle is erasure-conformant iff every removed concept is a conformant Tombstone, every referenced certificate resolves, and no Tombstone frontmatter, body, or log entry contains recoverable personal data. Mechanically checkable and byte-reproducible.
## Certificate format: intentionally out of scope
Format, not platform. OKF would define only the pointer convention and the no-PII / commitment rules. The certificate is the cryptographic claim about the real data; the Tombstone is the conformant, portable marker of it. The cert spec belongs in an open companion, not here.
## Worked sample (already built)
A self-contained sample backs this — a concept → Tombstone transition with a real, recomputable commitment:
https://github.com/cayerbe/knowledge-catalog/tree/okf-erasure-profile-sample/okf/bundles/erasure-sample
It validates against this repo's own reference tooling: every doc including the Tombstone passes `OKFDocument.validate()`, and the viewer renders the Tombstone as a live node with its inbound edges intact. `verification/verify.py` recomputes the HMAC commitment to a byte-identical match. (It uses relative cross-links to sidestep #48 — the viewer renders zero edges for the spec's absolute links.)
Happy to open it as a PR and add a deterministic, byte-reproducible conformance check for the erasure profile if the direction is useful — same proof-of-concept spirit as the enrichment agent and visualizer shipped with the spec.
---
*Related: #47 — the `timestamp` trust-seam discussion. The commitment + certificate here introduce a producer-custody trust seam in the same spirit, so the threads touch.*
Contributor guide
Assessment
This issue has not been assessed yet.