Separate authentication and entitlements, add federated DRM

[jdevalk]

Summary

• Separates auth (repository authentication) from entitlements (vendor-controlled access policy), resolving the conflation of authentication, authorization, and DRM in the existing auth property.
• Adds FairEntitlementService as a new DID Document service type, giving vendors a trust anchor for entitlement verification that survives repository changes.
• Defines an entitlement verification protocol with JWT-based entitlement proofs that can be validated by repositories, aggregators, and caches.
• Writes the ext-auth.md extension defining bearer, basic, and oauth2 authentication methods (previously empty).
• Adds entitlement types to the registry: subscription, purchase, license-key, free-registration.
• Increases the description character limit from 140 to 250 characters (spec and JSON schema).

How it works

1. Vendor registers a FairEntitlementService in their DID Document (trust anchor)
2. Package metadata specifies entitlements with type, service URL, and user-facing hints
3. Client validates the service URL matches the DID Document
4. Client verifies the user's entitlement via POST to the vendor's service
5. Vendor returns a signed JWT proof; client presents it to the repository as a bearer token
6. Repository validates the JWT and serves the artifact

This means vendors control access regardless of which repository serves their package, and users keep their entitlements when packages move between repositories.

Files changed

• specification.md — Core spec changes (auth narrowing, entitlements, DID service, verification protocol, flow diagrams, description limit)
• schemas/metadata.schema.json — Updated description maxLength from 140 to 250
• ext-auth.md — Authentication methods extension (bearer, basic, oauth2)
• registry.md — Added entitlement types table
• docs/implementing/restricted.md — Updated implementation guide
• docs/restricted.md — Updated user-facing overview

Test plan

• Review all cross-references between spec, extension, and registry for consistency
• Walk through the installation flow for a free package (no entitlements) — should be unchanged
• Walk through the installation flow for a restricted package with entitlements
• Verify the DID Document example is valid
• Verify backward compatibility: existing auth-only packages still work

🤖 Generated with Claude Code

[toderash]

The approach works for me. Background for other reviewers: TYPO3 hackathon discussion of how deeply FAIR should get into this - the concept has always existed, with placeholders in the spec. The approach needs to remain agnostic about the authentication method or platform, not requiring a specific type - e.g., maybe it's not based on a license key; actual implementation should also support an expiry date or next-reauth check so it doesn't have to be done on. every. single. page. load.

[toderash]

Flagged a few points to look at, but not comprehensive & didn't set a specific resolution, so simply accepting those won't really work.

The basic need is to define a means for the entitlement to expire & force reauthentication when needed - e.g., every 8 hours or 30 days or never or after a specific timestamp, now+365 days or an absolute UTC date/time or whatever, so if a subscription is renewed out of band, it'll simply re-auth and keep going, or do whatever's appropriate if the subscription expires.

[toderash]

For type : subscription, should also add

"expires": <date/time as UTC>

[toderash]

Consider a require-reauth field, boolean false, after a time interval, or after a UTC timestamp

need a means of forcing a re-check for subscriptions, license expiry, or enforce reauth (oauth) as needed.

[toderash]

and when reauthentication must occur, if applicable.

[toderash]

"auth-expiry": "----",

[jdevalk]

@toderash thanks for the review. I treated your inline comments as pointing at one underlying need — vendors must be able to control re-verification cadence, on any auth method, without forcing a check on every page load — rather than as four separate field requests, and the design landed slightly different from your suggestions. Walking through it so you can push back where I got it wrong:

1. The JWT proof's exp claim is now the authoritative re-verification deadline. It already existed but had a 24-hour cap; I removed the cap and replaced it with discretionary guidance + per-type examples. So a subscription proof can be valid for 30 days, a license-key proof can mirror the licence's own expiry (your "now+365 days" case), a high-security plugin can issue 8-hour proofs, and a free-registration can live for a year. The entitlement service picks the value at issuance — the metadata stays agnostic about auth method and entitlement model, which I think matches your March 21 note about not requiring a specific type.

This means clients are required to cache proofs until exp and refresh on 401/403 from the repository. They explicitly SHOULD NOT re-verify on every page load when a non-expired proof exists.

2. Added require-reauth: boolean on the entitlements object for the case where vendors do need to force a re-check on every protected action (per-seat enforcement, frequently-revoked entitlements). Default false. This is the bypass for "no caching, ever" — complementary to exp, not a replacement.

3. New "Caching and Re-verification" section in the spec spelling out exactly when a cached proof must be discarded:

• exp reached (with clock-skew margin),
• Repository or cache returns 401 Unauthorized while presenting the proof (treated as revocation),
• Entitlement service returns 403 Forbidden on refresh.

If a refresh returns 401/402, clients prompt the user for new credentials.

4. Updated docs/implementing/restricted.md with a "When entitlements expire and how often clients re-check" walkthrough covering each entitlement type, plus a require-reauth: true example for the strict-enforcement case. This is what the four inline comments on lines 49/66/70/75 of the original review map to.

5. Registry: added a non-normative "Typical proof lifetime" column per entitlement type so vendors have somewhere to look when choosing an exp.

6. Schema: entitlements previously relied on additionalProperties: true. Now properly defined in metadata.schema.json with all six fields. npm test is green on both test fixtures.

Why not a metadata-level expires / auth-expiry field as you suggested? I worried that would split the source of truth — the JWT already carries an authoritative expiry that repositories and caches must check, so adding a parallel metadata field invites drift (metadata says 30 days, JWT says 1 hour, who wins?). Keeping exp on the proof as the single deadline and using require-reauth only as a binary cache-bypass felt cleaner. Happy to revisit if you'd rather have the field on metadata as well.

Also pulled in main and resolved the conflicts: integrated last_updated and latest-security-release into the metadata table alongside entitlements, kept the 250-char description limit, normalized Client/Repository/Package capitalization throughout.

Ready for another look when you have time.