diff --git a/README.md b/README.md index 2885aff..d34414d 100644 --- a/README.md +++ b/README.md @@ -53,11 +53,13 @@ An operator can subscribe to an IPNS name and let TruthGate resolve it on a sche ### TruthGate Pointer protocol -TruthGate supports the **TruthGate Pointer protocol (TGP)**: a deliberately small convention in which an IPNS identity publishes a tiny `tgp.json` file that points to one current immutable CID. +TruthGate supports the **TruthGate Pointer protocol (TGP)**: a small structured layer in which an IPNS identity publishes a lightweight control bundle whose `tgp.json` points to the current immutable application CID. -TGP keeps the mutable layer light, makes freshness checks inexpensive, allows the current target to be cached normally, and supports clear unpin-and-garbage-collection workflows when content is removed. It intentionally does not publish a browsable history through the pointer. +TGP deliberately trades one additional resolution hop for a predictable machine-readable pointer, inexpensive freshness checks, normal immutable caching of the application, a browser-capable `index.html` fallback, and a stable place for future routing behavior. The public IPNS location can guide IPFS-aware browsers, ordinary browsers, and fallback routes without making the full application DAG serve as the control record. -TGP is an operational protocol, not a legal shield. It cannot erase copies retained by third parties, prevent archiving, or make an operator immune from legal obligations. See the [TGP documentation](docs/tgp/index.md) for the specification, rationale, gateway behavior, and legal limitations. +IPNS can already move to a new CID, and Kubo can already unpin and garbage-collect old content. TGP does not create those capabilities. Its retention benefit is that it gives TruthGate a consistent boundary around which current-only, bounded-history, selected-release, or archival policies can be expressed and automated. Updating a pointer alone does not delete older CIDs or copies retained by other nodes. + +See the [TGP documentation](docs/tgp/index.md) for the rationale, wire specification, client resolution, publisher workflow, and gateway behavior. ### Static-site publishing @@ -135,7 +137,7 @@ The documentation describes the current defaults and their limits without preten - TruthGate does not replace IPFS or Kubo. - TruthGate is not a blockchain or a new content network. - TruthGate does not make third-party copies of a CID disappear. -- TGP does not provide legal immunity or guaranteed global deletion. +- TGP does not make old CIDs globally revocable or replace Kubo pin and garbage-collection operations. - A mapped HTTPS domain is still an HTTP delivery path; the content remains independently addressable by CID. - TruthGate is not intended to expose Kubo's unrestricted local RPC interface directly to anonymous internet users. diff --git a/docs/tgp/faq.md b/docs/tgp/faq.md index 510d91f..6dade04 100644 --- a/docs/tgp/faq.md +++ b/docs/tgp/faq.md @@ -2,11 +2,31 @@ ## Why not point IPNS directly at the full site? -You can. TGP is useful when clients and gateways benefit from a tiny, explicit current-pointer document and a narrow mutable contract. +You can. Direct IPNS is valid and already supports moving the same identity to a new CID. -## Does TGP delete old content? +TGP adds a small, predictable control bundle for clients, gateways, browser fallback behavior, retention-policy automation, and future routing metadata. It is a trade: one additional content-resolution hop for those capabilities. -No. It supports updating the pointer, unpinning locally, and garbage collecting local blocks. Other nodes may retain copies. +## Does TGP make old content removable? + +Not by itself. Direct IPNS publishers can already update the name, unpin old content, remove retaining references, and let Kubo garbage-collect eligible local blocks. + +TGP gives TruthGate a consistent boundary around which those retention operations can be configured and automated. The actual removal work still belongs to Kubo and the publishing implementation. + +## Does updating TGP delete old content? + +No. Updating the pointer only changes the advertised current target. Old CIDs may remain pinned, referenced, cached, archived, or retained by other nodes. + +## Why make retention explicit? + +Different applications need different policies: + +- retain only the current deployment; +- keep the last few deployments; +- preserve selected tagged releases; +- maintain a separate complete archive; +- keep operational audit records without publishing a history catalog. + +TGP does not force one choice. It provides a stable place for TruthGate to express and enforce the selected lifecycle. ## Is `tgp` version `1` or `1.1`? @@ -22,20 +42,16 @@ Yes. V1 clients must ignore unknown fields. ## Can `current` be an HTTP URL? -No. V1 defines a CID or `/ipfs/` path. Allowing arbitrary URLs would create redirect and trust problems. +No. V1 defines a CID or `/ipfs/` path. Allowing arbitrary URLs would create redirect and trust problems. Browser routing belongs in the optional helper or a future explicitly versioned extension. ## Is `index.html` required? -No. It is an optional browser helper. - -## Is `legal.md` required? - -No. It is optional and informational. Its presence must not block resolution. +No. It is an optional browser helper. Machine clients resolve `tgp.json` directly. ## Can I keep deployment history? -Yes, but TGP does not define a public history list. Keep audit history outside the pointer. +Yes. TGP does not define a public history list. Keep history in a separate operator database, Git repository, logging system, or archive. ## Does it work with IPFS Companion? -A browser redirect to `/ipfs/` can be handled by an IPFS-aware browser environment or ordinary gateway routing. +Yes. A browser helper can detect an IPFS-aware environment and navigate to a direct `/ipfs/` destination that Companion or another integration can handle. diff --git a/docs/tgp/gateway-behavior.md b/docs/tgp/gateway-behavior.md index 118fb78..46b781e 100644 --- a/docs/tgp/gateway-behavior.md +++ b/docs/tgp/gateway-behavior.md @@ -8,10 +8,10 @@ For a TGP-backed IPNS host: 1. resolve and validate `tgp.json`; 2. identify the current target; -3. serve or redirect to that target; +3. serve, embed, or redirect to that target according to gateway policy; 4. use short caching for the pointer; 5. use normal immutable caching for the target; -6. expose the optional legal notice; +6. support a browser fallback when the TGP root provides one; 7. reject malformed pointers rather than guessing. ## Current-target restriction @@ -20,18 +20,27 @@ A gateway MAY restrict the TGP host to the CID advertised by `current`. This prevents the same host from becoming a general-purpose path to unrelated or previously advertised CIDs. -It does not prevent users from fetching a known old CID through another gateway or node. +It does not prevent users from fetching a known old CID through another gateway or node, and it does not remove that CID from any repository. ## Browser fallback -An optional `index.html` can fetch `tgp.json` and redirect. +An optional `index.html` can fetch `tgp.json` and choose an appropriate destination. + +A browser helper may: + +- detect an IPFS-aware browser environment; +- navigate directly to `/ipfs/`; +- try a configured Web2 destination; +- use a gateway or redirect document; +- provide direct recovery links when extensions or blockers interfere. The fallback should: -- avoid arbitrary URL redirects; +- avoid arbitrary unvalidated URL redirects; - identify stale fallback behavior; - preserve subpaths only when deliberately specified; -- fail clearly when the pointer is invalid. +- fail clearly when the pointer is invalid; +- remain optional for machine clients. ## Caches diff --git a/docs/tgp/index.md b/docs/tgp/index.md index 6704863..8349f16 100644 --- a/docs/tgp/index.md +++ b/docs/tgp/index.md @@ -1,43 +1,58 @@ # TruthGate Pointer protocol -The **TruthGate Pointer protocol (TGP)** is a small convention for using an IPNS identity to advertise one current immutable IPFS target. +The **TruthGate Pointer protocol (TGP)** is a small convention for publishing a structured control bundle through an IPNS identity. Its required `tgp.json` file identifies one current immutable IPFS target. -An IPNS root contains a required `tgp.json` file. Clients read the pointer and then load the CID in `current`. +```text +IPNS identity + │ + ▼ +TGP control bundle +├── tgp.json required machine-readable pointer +└── index.html optional browser resolver and fallback + │ + ▼ +current application CID +``` ```json { "tgp": 1, "ts": "2026-07-25T17:00:00Z", "current": "bafy...", - "domainName": "example.com", - "legal": "/legal.md" + "domainName": "example.com" } ``` -## Why it matters +## Why use an extra hop? + +IPNS can already point directly at an application CID. TGP deliberately adds one content-resolution hop to gain a stable, predictable control layer. + +That layer supports: + +- a tiny document for inexpensive freshness checks; +- an explicit current application target; +- normal immutable caching after resolution; +- a browser-capable fallback location at the IPNS root; +- consistent behavior for IPFS-aware and ordinary browsers; +- gateway policies based on a known pointer contract; +- explicit current-only, bounded-history, selected-release, or archival retention policies; +- room for future routing and fallback metadata without changing the application DAG. -TGP keeps the mutable object tiny while the application remains immutable and cacheable. +## Relationship to IPNS and Kubo -It supports: +TGP does not replace IPNS. IPNS supplies the signed mutable identity, sequence handling, routing, and name resolution. -- inexpensive freshness checks; -- one current target; -- simple client resolution; -- ordinary caching of the immutable CID; -- unpin and garbage-collection workflows; -- gateway policies that only serve the advertised target; -- clear separation between current deployment and off-pointer audit history. +TGP also does not create deletion or garbage collection. A direct IPNS publisher can already update the name, remove old pins and references, and allow Kubo to garbage-collect eligible local blocks. -## What it does not do +TGP's retention benefit is organizational: TruthGate receives a consistent boundary around which retention policy and deployment lifecycle can be expressed, automated, monitored, and verified independently from the application content itself. -TGP cannot: +## Technical limits -- erase blocks held by another node; -- revoke a CID globally; -- prevent caches, mirrors, archives, screenshots, or copies; -- guarantee that deleted content becomes undiscoverable; -- provide legal immunity; -- replace legal advice or an operator's compliance obligations. +- Updating `tgp.json` does not delete an older CID. +- Removing local content requires handling every pin and reference that retains it. +- Other nodes, gateways, caches, mirrors, or users may retain copies independently. +- TGP does not make CIDs globally revocable. +- The pointer bundle is an additional IPFS object and resolution hop. ## Documentation @@ -46,8 +61,6 @@ TGP cannot: - [Client resolution](client-resolution.md) - [Publisher workflow](publisher-workflow.md) - [Gateway behavior](gateway-behavior.md) -- [Legal considerations](legal-considerations.md) -- [Legal-notice template](legal-notice-template.md) - [FAQ](faq.md) ## Version terminology diff --git a/docs/tgp/legal-considerations.md b/docs/tgp/legal-considerations.md deleted file mode 100644 index f821926..0000000 --- a/docs/tgp/legal-considerations.md +++ /dev/null @@ -1,53 +0,0 @@ -# TGP legal considerations - -This page is informational and is not legal advice. - -## Operational purpose - -TGP gives an operator a clear current pointer and a practical workflow for: - -- updating the advertised target; -- avoiding a public history catalog in the pointer; -- unpinning removed content locally; -- running local garbage collection; -- documenting the current deployment; -- responding to moderation or takedown decisions. - -## Limits - -TGP cannot: - -- delete copies retained by another IPFS node; -- prevent third-party pinning; -- control public gateways, mirrors, caches, archives, or screenshots; -- revoke knowledge of an old CID; -- guarantee compliance with any law or contract; -- determine who is legally responsible for content; -- make an operator immune from claims. - -## Operator responsibility - -Operators remain responsible for: - -- the content they publish or intentionally retain; -- access-control choices; -- notices and contact procedures; -- applicable moderation and takedown processes; -- record retention; -- legal obligations in relevant jurisdictions. - -Consult qualified counsel for a production legal policy. - -## Claims documentation should avoid - -Do not describe TGP as: - -- legal immunity; -- guaranteed deletion; -- a right-to-erasure implementation by itself; -- proof that the operator never hosted content; -- protection from archives or independent peers. - -A more accurate statement is: - -> TGP can reduce the mutable and locally retained surface an operator intentionally maintains, while making the current target and removal workflow explicit. diff --git a/docs/tgp/legal-notice-template.md b/docs/tgp/legal-notice-template.md deleted file mode 100644 index 996feca..0000000 --- a/docs/tgp/legal-notice-template.md +++ /dev/null @@ -1,38 +0,0 @@ -# Informational TGP notice template - -This is a technical starting point, not legal advice or a jurisdiction-specific policy. Have qualified counsel review any notice used in production. - -```markdown -# Current-content pointer notice - -This IPNS identity uses the TruthGate Pointer protocol (TGP) to identify one current IPFS content target. - -The current target is declared in `/tgp.json`. - -The operator may update that target, remove local pins, and run local repository garbage collection. These actions affect the operator's own systems. They do not delete or control copies that may have been retained by independent IPFS nodes, gateways, caches, mirrors, archives, or users. - -A CID is content-addressed and may remain retrievable from third parties after the operator stops advertising or retaining it. - -For questions or reports concerning the current target, contact: - -- Operator: [NAME] -- Contact: [CONTACT METHOD] -- Policy or jurisdiction information: [OPTIONAL] - -Last updated: [DATE] -``` - -## Usage - -1. Save the reviewed notice as `/legal.md` in the TGP root. -2. Add: - -```json -{ - "legal": "/legal.md" -} -``` - -to `tgp.json`. -3. Keep the notice contact information current. -4. Do not claim that the notice changes third-party behavior. diff --git a/docs/tgp/publisher-workflow.md b/docs/tgp/publisher-workflow.md index d407c43..a6cfdc8 100644 --- a/docs/tgp/publisher-workflow.md +++ b/docs/tgp/publisher-workflow.md @@ -4,16 +4,15 @@ - an IPNS key controlled by the publisher; - the current site root CID; -- optional domain name; -- optional legal notice. +- an optional domain name; +- optional browser-routing configuration. ## Build the pointer directory ```text tgp-root/ ├── tgp.json -├── index.html optional -└── legal.md optional +└── index.html optional browser resolver and fallback ``` Example `tgp.json`: @@ -23,8 +22,7 @@ Example `tgp.json`: "tgp": 1, "ts": "2026-07-25T17:00:00Z", "current": "bafy...", - "domainName": "example.com", - "legal": "/legal.md" + "domainName": "example.com" } ``` @@ -32,12 +30,14 @@ Example `tgp.json`: 1. Validate the site CID. 2. Generate `tgp.json`. -3. Add the pointer directory to IPFS. -4. Publish the resulting pointer-directory CID through the IPNS key. -5. Verify IPNS resolution. -6. Fetch and validate `tgp.json`. -7. Fetch the current site CID. -8. Verify mapped-domain metadata. +3. Generate the optional browser helper. +4. Add the pointer directory to IPFS. +5. Publish the resulting pointer-directory CID through the IPNS key. +6. Verify IPNS resolution. +7. Fetch and validate `tgp.json`. +8. Test the browser helper in ordinary and IPFS-aware browser contexts. +9. Fetch the current site CID. +10. Verify mapped-domain metadata. ## Updating @@ -45,25 +45,37 @@ For a new deployment: 1. publish the new site and obtain its CID; 2. update `current` and `ts`; -3. add the new pointer directory; +3. build and add the new pointer directory; 4. update IPNS; 5. wait for resolution; -6. verify clients; -7. apply old-target retention policy. +6. verify machine clients and browser behavior; +7. apply the separately configured old-target retention policy. -## Removing old content locally +## Retention is separate from pointer publication -When policy permits: +Publishing a new TGP root changes the advertised current target. It does not automatically remove the previous application CID or previous pointer bundle from a Kubo repository. + +A complete current-only or bounded-history implementation must account for: + +- direct recursive pins; +- parent or indirect pins; +- MFS references; +- watched-IPNS retention; +- other local applications or archives; +- remote pinning services; +- local blockstore garbage collection. + +When an old CID is no longer protected by any required reference, Kubo operations may include: ```bash ipfs pin rm ipfs repo gc ``` -Only run garbage collection with a complete understanding of other pins and repository users. +Only run garbage collection with a complete understanding of other pins and repository users. These operations affect the local node; they cannot remove copies retained elsewhere. -This removes eligible blocks from the local node. It cannot remove blocks pinned or cached elsewhere. +TGP supplies the stable control boundary for retention policy. Kubo supplies the actual pin and repository operations. -## Audit history +## Deployment history -Keep deployment history in an operator database, Git repository, logging system, or other off-pointer record. TGP does not define a public history array. +TGP does not define a public history array. Keep deployment history in an operator database, Git repository, logging system, or separate archive when desired. diff --git a/docs/tgp/rationale.md b/docs/tgp/rationale.md index 1520c55..347efd4 100644 --- a/docs/tgp/rationale.md +++ b/docs/tgp/rationale.md @@ -1,54 +1,87 @@ # TGP rationale -## The problem +## The deliberate trade -A static application is naturally represented by an immutable CID. Users and applications still need a stable name that can move to a new build. +An application can use IPNS directly: -IPNS provides the signed mutable identity. A publisher can point that identity directly at the complete site, but clients that only need to discover the current deployment must resolve the entire mutable root conceptually as the application. +```text +IPNS → application CID +``` + +TGP chooses: + +```text +IPNS → small control bundle → application CID +``` + +That is one additional content-resolution hop. TGP exists because the control layer created by that hop is useful enough to justify the cost. + +## What IPNS already provides + +IPNS is a signed, mutable pointer to a path. It can be updated to a new CID without replacing the identity. IPNS does not inherently require an operator to keep every previous target pinned or publish a browsable deployment history. + +Kubo already provides the storage operations needed to remove eligible local content: pins and references can be removed, and repository garbage collection can remove unprotected blocks. -TGP narrows that mutable surface. +TGP does not claim those capabilities as inventions of the protocol. ## The pointer model The IPNS identity points to a small directory containing: ```text -/tgp.json -/index.html optional -/legal.md optional +/tgp.json required +/index.html optional browser resolver and fallback ``` -`tgp.json` points to the current immutable site CID. +`tgp.json` gives software a known place to discover the current immutable application CID. `index.html` can make the IPNS location useful to a person rather than exposing only raw JSON. -## Operational benefits +TruthGate's browser fallback can resolve the pointer, recognize an IPFS-aware browser environment, try a configured Web2 route, navigate to a direct CID path, and provide recovery links when automatic navigation is blocked. -### Light mutable payload +## Primary benefits -The pointer is small and cheap to fetch, validate, mirror, and monitor. +### Lightweight control-plane reads -### Immutable application caching +A monitor or client can fetch and validate a small pointer document rather than treating the complete application root as the control record. -After resolution, `/ipfs/` can use ordinary immutable-content caching. +### Stable browser landing point -### Clear current target +The IPNS identity remains a useful location of its own. The control bundle can direct ordinary browsers, IPFS-aware browsers, and fallback paths toward the current deployment. + +### Application-independent routing + +Routing and fallback behavior can evolve without embedding that logic into every application build. The pointer bundle provides a natural seam for future destination, transport, gateway, or capability metadata while the application CID remains immutable. + +### Explicit retention policy -Clients do not need to infer which object in a directory is the deployment. +Direct IPNS does not prevent removal, but it also does not define an application-level retention convention. -### Removal workflow +TGP gives TruthGate a stable lifecycle boundary around which an operator can choose policies such as: -An operator can: +- current target only; +- the most recent bounded number of deployments; +- selected tagged releases; +- a separate archival policy; +- no public history catalog while audit records remain elsewhere. -1. update the pointer; -2. unpin an old target locally; -3. run repository garbage collection; -4. stop intentionally advertising that target through the IPNS identity. +The protocol does not perform unpinning or garbage collection by itself. TruthGate or another publisher must implement the selected policy correctly. + +### Immutable application caching + +After resolution, `/ipfs/` remains ordinary immutable content and can use normal IPFS and HTTP caching. + +### Clear current target -This controls the operator's own node and pointer. It does not control independent third-party copies. +Clients do not need to infer which object in the application directory represents the active deployment. -### No default history catalog +## Costs and limits -TGP does not define a historical list. Audit records can exist elsewhere without becoming part of the public pointer contract. +- Resolution requires one additional IPFS object. +- Pointer freshness and application caching require different policies. +- A malformed or unavailable pointer can block resolution even when the application CID still exists. +- Updating the pointer does not remove older content from the local repository. +- Local removal requires clearing every retaining pin or reference and allowing garbage collection to remove eligible blocks. +- Independent nodes may retain older CIDs. ## Why IPNS still matters -TGP does not replace IPNS signing, sequence handling, routing, or name resolution. It uses IPNS as the authenticated mutable identity and defines the payload clients expect after resolution. +TGP uses IPNS as the authenticated mutable identity. It does not replace IPNS signing, sequence handling, routing, or name resolution; it defines the payload clients expect after IPNS resolution. diff --git a/docs/tgp/specification-v1.md b/docs/tgp/specification-v1.md index 9298106..3da678b 100644 --- a/docs/tgp/specification-v1.md +++ b/docs/tgp/specification-v1.md @@ -15,6 +15,8 @@ A conforming TGP v1 IPNS root MUST provide: The path is relative to the root resolved by the IPNS identity. +A root MAY also contain an `index.html` browser helper or other non-normative files. Clients MUST NOT require those files to resolve the pointer. + ## 2. Media type and encoding `tgp.json` MUST be valid UTF-8 JSON. @@ -34,8 +36,7 @@ Example: "tgp": 1, "ts": "2026-07-25T17:00:00Z", "current": "bafy...", - "domainName": "example.com", - "legal": "/legal.md" + "domainName": "example.com" } ``` @@ -76,19 +77,6 @@ The target MUST identify an IPFS content path. A v1 client MUST NOT invent a tar The primary associated DNS name. Clients MUST NOT treat this unsigned field separately from the trust provided by the resolved IPNS record. -### `legal` - -- Type: string -- Required: no - -A path to an informational notice, normally: - -```text -/legal.md -``` - -The notice MUST NOT be required for pointer resolution. - ### Unknown fields Clients MUST ignore unknown fields so compatible metadata can be added without breaking v1 readers. @@ -126,21 +114,21 @@ A client MAY retain a last-known-good target for availability, but SHOULD indica - malformed JSON: fail; - unsupported version: fail; - missing or empty `current`: fail; -- invalid target: fail; -- missing legal notice: continue resolution. +- invalid target: fail. Clients MUST NOT guess a CID from unrelated files. -## 7. Optional files +## 7. Optional browser helper + +A TGP root MAY provide: ```text /index.html -/legal.md ``` -`index.html` MAY provide browser-oriented resolution. +The browser helper MAY fetch `tgp.json`, select an appropriate route, and navigate or render the current target. -`legal.md` MAY provide operator information and limitations. +It MUST NOT change the machine-readable meaning of `tgp.json`, and clients MUST NOT require it for protocol resolution. ## 8. JSON Schema @@ -166,9 +154,6 @@ Clients MUST NOT guess a CID from unrelated files. }, "domainName": { "type": "string" - }, - "legal": { - "type": "string" } } }