ipfs / ipfs/specs

Include IPNS Record in Gateway CAR responses

Open
#369 8 comments 2 reactions 0 assignees View on GitHub
IPIP need/triage
Dominant language
HTML
Stars
1.2k
Forks
247
Avg merge
5d 21h
Merged PRs (30d)
4

Description

[IPIP-351: IPNS Signed Records Response Format on HTTP Gateways](https://github.com/ipfs/specs/pull/351) will return a raw IPNS record, allowing a custom light client to verify IPNS without having to run DHT client.

Users [asked](https://discuss.ipfs.tech/t/ipns-records-as-ipld-objects-in-car-archives/15853) for the ability to export both CIDs and IPNS record into a CAR, transport over sneakernet and load this on airgapped node, which is a good use case.

Another use case is Decentralized Gateway WG, which could benefit from the ability to have a single round-trip that includes full [or partial](https://github.com/ipfs/specs/issues/348) CAR with content + ipns-record.

Broad strokes UX we want to accommodate:

```console
$ curl http://gateway.foo/ipns/{id}?format=car&something > ipns-site-dump.car
$ ipfs import ipns-site-dump.car # imaginary command that goes beyond DAGs
$ ipfs resolve /ipns/{id} # works, even in offline mode
$ ipfs dag stat /ipns/{id} # works, even in offline mode
```

Initial notes / subtasks

- [x] need to add a new `ipns-record` codec, to indicate special meaning of this additional block. Done: https://github.com/multiformats/multicodec/pull/312
- [ ] Extend [Trustless Gateway spec](https://specs.ipfs.tech/http-gateways/trustless-gateway/) to support verifiable responses of `/ipns/{libp2p-key}` paths: decide if returned CAR should include two roots. One for data, second for `ipns-record` block. Specify if ipfs-records should be at the beginning of the CAR returned by `/ipns/{id}?format=car[&something?]` - to allow quick validation of response without wasting time for hashing invalid blocks that do not belong to CID in IPNS record.
- [x] `?format=ipns-record` on `/ipns/{key}` landed in IPIP-351 ([spec](https://specs.ipfs.tech/http-gateways/trustless-gateway/#get-ipns-key-params))
- [ ] record inside the CAR response
- [ ] Kubo CLI should have top level `import` / `export` that operates on content paths (instead of raw dags like `ipfs dag` versions), include all parent blocks and not just the final terminating element recursively, and be smart enough to use `ipns-record` and import it to local namesys cache if a block with ipns-record codec is present in a CAR

## Status as of 2026Q3

Nobody is working on this. Summary of what exists and what is missing, so it can be picked up.

**Trustless two-step retrieval works today, over plain HTTP:**

1. `GET /ipns/{name}?format=ipns-record` ([IPIP-351](https://specs.ipfs.tech/http-gateways/trustless-gateway/#get-ipns-key-params)): the client verifies the signature and resolves the record to `/ipfs/{cid}`, or stops on mismatch.
2. `GET /ipfs/{cid}?format=car` with `dag-scope`, `entity-bytes` and `order=dfs` ([IPIP-402](https://specs.ipfs.tech/ipips/ipip-0402/)): the client verifies each block as it arrives and drops the connection on the first block that fails its hash or is not expected in the DAG.

**What is missing is the single round trip.** `GET /ipns/{name}?format=car` today returns the CAR of the resolved content without the record, so the client cannot verify the IPNS step from that response alone. The smallest useful shape: a CAR with the `ipns-record` block (codec `0x0300`) first, then the IPIP-402 stream from the root the record points at. The client checks the record before hashing anything else and can drop the connection after the first bad block. Plain HTTP, no new protocol or transport needed.

Open questions, unchanged from the list above:

- CAR roots: only the record, only the data root, or both.
- Request signal: an explicit `format` value or a CAR content-type parameter ([IPIP-412](https://specs.ipfs.tech/ipips/ipip-0412/) style), so a client can tell a record-first CAR from a plain one served by an older gateway.

Kubo side: no content-path `import`/`export` exists, and `ipfs dag import` does not know the `ipns-record` codec.

Contributor guide

No contributing guide indexed for this repository

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.