Re: Proposal: Adding acl:paymentRequired predicate for HTTP 402 handling

st 9. 7. 2025 v 21:12 odesílatel Melvin Carvalho <melvincarvalho@gmail.com>
napsal:

>
>
> st 9. 7. 2025 v 3:23 odesílatel elf Pavlik <elf-pavlik@hackers4peace.net>
> napsal:
>
>> Hi Melvin,
>>
>> On 2025-07-08 02:16, Melvin Carvalho wrote:
>> > Why?
>> > ====
>> >
>> > Many Solid agents run on usage-based quotas
>> > (API tokens, Streaming Chat Interfaces, storage bytes, etc.).
>> > Today servers have no *standard* way to:
>> >
>> > * signal “the request was good, but please pay a bit first”,
>> > **and**
>> > * tell the client where to send that payment.
>> >
>> > Applications therefore cook up ad-hoc headers and status codes,
>> > breaking interoperability.
>> >
>> > One predicate plus the already standard HTTP 402 closes that gap.
>>
>> Have you consider adding your use case to https://github.com/w3c/lws-ucs
>>
>> > Example ACL
>> > -----------
>> >
>> > @prefix acl:
>> > [http://www.w3.org/ns/auth/acl#](http://www.w3.org/ns/auth/acl#) .
>> > @prefix foaf: [http://xmlns.com/foaf/0.1/](http://xmlns.com/foaf/0.1/)
>> > .
>> >
>> > <#paid-read>
>> > a               acl:Authorization ;
>> > acl:accessTo    </data/> ;
>> > acl:mode        acl:Read ;
>> > acl:agentClass  foaf:Agent ;
>> > acl:paymentRequired "0.0005"^^xsd:decimal .
>> >
>> > Server behaviour (normative)
>> > ============================
>> >
>> > * Evaluate the requester’s **current balance** (ledger details are
>> >   implementation-specific).
>> > * If balance < required, respond:
>> >
>> > HTTP/1.1 402 Payment Required
>> > Link: https://pay.example/topup ; rel="payment"
>> > Pay-Balance: "-0.0001"
>> > Pay-Required: "0.0005"
>> >
>> > * After the client tops up and retries, normal `2xx` processing
>> >   resumes.
>> >
>> > Open questions
>> > ==============
>> >
>> > 1. **Currency unit** —  keep it server-wide (simplest) or add
>> > another
>> >    predicate for per-rule currency?
>> > 2. **Headers** —  are `Pay-Balance` / `Pay-Required` worth
>> > standardising
>> >    or should there be a problem JSON body alone carry the numbers?
>> > 3. **Ledger location** —  should the spec normatively reference a
>> >    `webledger.json` (or similar) so clients can fetch balances?
>>
>> You haven't fully described your use case, for example I don't know
>> where the following assumption is coming from.
>> It seems that the end user has some pre-established relation with the
>> resource server, and this relation is also somehow known to the client
>> used by that end user.
>>
>> Do you consider spontanous interactions as out of scope? For example
>> where the end user with their client follows its nose to a resource
>> hosted on a server where they have no pre-established relation.
>>
>
> Hi Elf
>
> Thanks for the constructive feedback
>
> Why we assumed a prior account: we’re laser-focused on metering repeat-use
> APIs (think GPT-style tokens) for AI services across your entire pod (aka
> workspace). In that world the caller already has an account, so every hit
> uses a service and we debit atomically, or return 402 if empty.
>
> Spontaneous visits are in scope. Happy path:
>
> Client GETs resource, has no account → gets 402 with
> Link: </.well-known/webledgers/topup>; rel="payment".
>
> Follows link, pays (tokens, card, whatever).
> Server issues a fresh Account-ID + starter credits.  Freemium with
> upgrade, for example.
>
> Client retries with the signed debit proof. Done.
>
> (We’re experimenting with server-minted throw-away DIDs so no signup
> friction.)
>
> Next step: write up a “micro-metered API” use-case to flesh out the actors
> and interactions.
>
> Let me know if I missed an edge-case you care about.
>

Regarding a user story:

Think of visiting a new online photo editor: you hit “export,” it politely
says, “that’ll be five cents,” you tap pay, and the download begins. That
is what acl:paymentRequired captures: a simple, standard way to ask for a
bit of money from someone's balance, one they can top up any time. The
credit it deducts lives in a tiny linked-data ledger stored by the photo
editing pod.

Here's the linked data ledger component that I've been working on for a
while: https://webledgers.org/

Tie this workflow together with the ACL and I think it's possible to create
a working prototype.


>
> Cheers!
> Melvin
>
>
>>
>> Cheers!
>> elf Pavlik
>>
>>