Donate to Postulo/postulo

• https://buymeacoffee.com/tiagoagueda

---

See the documentation for more details on donation links.

Name each capture's posting by an opaque key on the API (#711) #1077

Merged

tiagoagueda merged 1 commit from 711-captures-posting-key into main 2026-10-29 09:37:28 +00:00

Conversation 0 Commits 1 Files changed 6 +197 -2

tiagoagueda commented 2026-10-28 15:14:41 +00:00

Owner

• Copy link
• Copy Markdown

The browser extension counts the postings waiting for review once each, merging
Postulo's list with its own unsent captures, and to do it carried a port of
same_url() with cases of its own. Two copies of one rule drift, and the day they
did the badge and the review list would disagree with Postulo about what is one
posting.

Every capture the API answers with (GET /captures, POST /captures, the rendering
call) now carries posting_key: an HMAC of the stored Capture.url_key and the
owner's id, under a key derived from the instance's key with a domain prefix of
its own (secrets.posting_key, beside backup_mac). Two captures of one posting
share it, two postings do not, and it is stable while the instance's key is.

Not the normalised address: a token holding only captures is not told the
address (#761), and a normalised one per row, or a bare SHA of it, would hand it
back. The keyed hash says nothing without the key, so it is told to that token
too. The owner's id is in it so two accounts' keys cannot be matched against each
other. An address with no host has an empty key, as same_url() matches nothing.

POST /captures/known answers each asked address's key as well, so a client can
put what it has not sent yet beside the list without reducing an address itself;
it tells a captures-only token nothing /known did not already say. The field is
described in the OpenAPI schema; the threat model says what a captures token sees.

Closes #711

Notes for review

• The key: each capture carries posting_key, an HMAC-SHA256 (keyed from POSTULO_FIELD_KEY, else SECRET_KEY) of the owner's id and the stored url_key.
  • It is the same for two captures of one posting.
  • It can't be turned back into the address. Capture-only tokens get it while url stays blank, as #761 requires.
• Decisions the issue left open:
  • The owner is part of the key, so keys don't match across accounts.
  • An address with no host gets an empty key rather than a hash of "", which would have counted every such capture as one posting.
  • POST /captures/known also returns the key for each address asked about, so the extension can key its unsent captures too. A capture-only token learns nothing new, since /known already says whether a capture exists.
  • The key changes if the instance's key does, and the wiki says so.
• Follow-up: the extension drops its own same_url() copy, filed on postulo-chromium.

🤖 Generated with Claude Code

The browser extension counts the postings waiting for review once each, merging Postulo's list with its own unsent captures, and to do it carried a port of same_url() with cases of its own. Two copies of one rule drift, and the day they did the badge and the review list would disagree with Postulo about what is one posting. Every capture the API answers with (GET /captures, POST /captures, the rendering call) now carries `posting_key`: an HMAC of the stored `Capture.url_key` and the owner's id, under a key derived from the instance's key with a domain prefix of its own (secrets.posting_key, beside backup_mac). Two captures of one posting share it, two postings do not, and it is stable while the instance's key is. Not the normalised address: a token holding only `captures` is not told the address (#761), and a normalised one per row, or a bare SHA of it, would hand it back. The keyed hash says nothing without the key, so it is told to that token too. The owner's id is in it so two accounts' keys cannot be matched against each other. An address with no host has an empty key, as same_url() matches nothing. POST /captures/known answers each asked address's key as well, so a client can put what it has not sent yet beside the list without reducing an address itself; it tells a captures-only token nothing /known did not already say. The field is described in the OpenAPI schema; the threat model says what a captures token sees. Closes #711 ## Notes for review - **The key:** each capture carries `posting_key`, an HMAC-SHA256 (keyed from `POSTULO_FIELD_KEY`, else `SECRET_KEY`) of the owner's id and the stored `url_key`. - It is the same for two captures of one posting. - It can't be turned back into the address. Capture-only tokens get it while `url` stays blank, as #761 requires. - **Decisions the issue left open:** - The owner is part of the key, so keys don't match across accounts. - An address with no host gets an empty key rather than a hash of "", which would have counted every such capture as one posting. - `POST /captures/known` also returns the key for each address asked about, so the extension can key its unsent captures too. A capture-only token learns nothing new, since `/known` already says whether a capture exists. - The key changes if the instance's key does, and the wiki says so. - **Follow-up:** the extension drops its own `same_url()` copy, filed on postulo-chromium. 🤖 Generated with [Claude Code](https://claude.com/claude-code)

tiagoagueda added 1 commit 2026-10-28 15:14:41 +00:00

Name each capture's posting by an opaque key on the API (#711) ... 72ce330b50

The browser extension counts the postings waiting for review once each, merging
Postulo's list with its own unsent captures, and to do it carried a port of
same_url() with cases of its own. Two copies of one rule drift, and the day they
did the badge and the review list would disagree with Postulo about what is one
posting.

Every capture the API answers with (GET /captures, POST /captures, the rendering
call) now carries `posting_key`: an HMAC of the stored `Capture.url_key` and the
owner's id, under a key derived from the instance's key with a domain prefix of
its own (secrets.posting_key, beside backup_mac). Two captures of one posting
share it, two postings do not, and it is stable while the instance's key is.

Not the normalised address: a token holding only `captures` is not told the
address (#761), and a normalised one per row, or a bare SHA of it, would hand it
back. The keyed hash says nothing without the key, so it is told to that token
too. The owner's id is in it so two accounts' keys cannot be matched against each
other. An address with no host has an empty key, as same_url() matches nothing.

POST /captures/known answers each asked address's key as well, so a client can
put what it has not sent yet beside the list without reducing an address itself;
it tells a captures-only token nothing /known did not already say. The field is
described in the OpenAPI schema; the threat model says what a captures token sees.

Closes #711

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

tiagoagueda force-pushed 711-captures-posting-key from 72ce330b50 to 2e01143c75 2026-10-29 09:36:10 +00:00 Compare

tiagoagueda merged commit 00e5dd3be9 into main 2026-10-29 09:37:28 +00:00

tiagoagueda deleted branch 711-captures-posting-key 2026-10-29 09:37:28 +00:00

tiagoagueda referenced this pull request from a commit 2026-10-29 09:37:29 +00:00

Name each capture's posting by an opaque key on the API (#711) (#1077)

Sign in to join this conversation.

Reviewers

No reviewers

Labels

Clear labels   

accessibility

Usable by everyone, including people with disabilities: one of the project's stated missions

  

authentication

Signing in, and proving who you are

  

breaking change

Changes behaviour or data in a way operators must act on

  

bug

Something does not do what it says it does

  

documentation

The wiki, the docs, or the words in the interface

  

enhancement

An improvement or a new capability

  

interface

The shape of the pages: what is where, and how it reads

  

internationalisation

Languages, regions, and the formats and symbols that go with them

  

observability

What an operator can see about a running instance: metrics, logs, health

  

performance

Uses fewer resources, or is more reliable, with no loss of features or accessibility

  

security

Keeping the code and the data secure: one of the project's stated missions

  

tier

1

Easy: small, self-contained, no prerequisites

  

tier

2

High-severity security: account access, personal data, the boundaries

  

tier

3

Foundations: prerequisite work that unblocks other issues

  

tier/4

Later: large features and long-horizon work

No labels

accessibility

authentication

breaking change

bug

documentation

enhancement

interface

internationalisation

observability

performance

security

tier

1

tier

2

tier

3

tier/4

Milestone

Clear milestone

No items

No milestone

Projects

Clear projects

No items

No project

Assignees

Clear assignees

No assignees

1 participant

Notifications

Subscribe

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference

Postulo/postulo!1077

No description provided.