Labrador DCA Plugin
The Labrador DCA plugin unlocks Labrador CMS articles whose paid sections are encrypted with Delegated Content Access (DCA), with Sesamy as the issuer that decides who may read them.
Overview
With DCA, Labrador encrypts each paid section of an article when it renders the page. The decryption keys are sealed so that only an issuer, here Sesamy, can open them. The reader's browser never receives readable paid content unless Sesamy grants access.
The plugin connects the two sides in the browser:
- It takes the unlock request Labrador's client API builds for issuer
sesamy. - It sends that request to the Sesamy API as the signed-in reader.
- It hands the content keys Sesamy returns back to Labrador, which decrypts and shows the sections.
Without access it tells Labrador so. The content stays locked, and the Sesamy paywall on the page is shown as usual.
Requirements
- The page is a Labrador page with DCA enabled, and Labrador has registered Sesamy as issuer
sesamywith your ECDH P-256 public key. See Publisher setup. - Sesamy JS 1.137.1 or later is loaded on the page through the scripts host bundle. With an older version the plugin is left out of the bundle.
- Your Labrador site's domain is registered as a trusted publisher for your vendor, so Sesamy can verify the pages Labrador signs.
Enable the Plugin
Enable it for your vendor in the vendor config:
{
"scripts": [{ "name": "labrador-dca" }]
}Or enable it for a single page through the bundle URL:
<script src="https://scripts.sesamy.com/s/acme/bundle.js?plugins=labrador-dca"></script>The plugin sends its request through Sesamy JS, so it uses the API endpoint and sign-in method Sesamy JS is configured with on the page, including a custom API domain with cookie authentication.
How Access Is Decided
Sesamy makes the same access decision as for other Sesamy-protected content:
- Signed link - the reader arrived with a Sesamy signed link (
sesamy_token, created withPOST /management/create-signed-link) for this article. The plugin sends the link Sesamy JS kept for the page, and Sesamy opens the article when the link is valid and names it. The reader doesn't need to sign in. - Entitlement - the reader owns an entitlement for the article URL, or for a pass Labrador signs into the page as covering the article.
- Paywall - otherwise the paywall Labrador signs into the page decides, including metered access. A metered read is counted only when the keys are delivered. Without a signed paywall, only an entitlement opens the content.
Passes and the paywall have to be signed because they decide whether keys are released. Pass and paywall references sent by the browser are ignored. Otherwise a reader who owns any of your passes could claim it covers every article, or pick a login or metered paywall for content behind a stricter one.
A signed link has to name the article Labrador signed, by its URL. A link created with a SKU also opens an article Labrador signs that SKU into entitlementScopes for, but the plugin only sends a link on the page whose URL it names. Metered grants, the short-lived links metered paywalls hand out, are not accepted: Sesamy evaluates the signed paywall itself. A signed link works until it expires and can't be withdrawn earlier, so keep the expiry short.
The article is identified by the URL and resource ID Labrador signs into the page. A prefixed Labrador ID such as article-100036 is matched as 100036, the content ID used on the page.
Keys for every page load
DCA keys are bound to one page render and have no expiry. Each page load asks Sesamy again, so a cancelled subscription or a used-up meter takes effect on the next load.
Publisher Setup
DCA needs a one-time exchange of keys between Labrador and Sesamy for each site.
Send Sesamy's Public Key to Labrador
Your vendor's ECDH P-256 public key is published in your vendor's key set, as the key with "use": "enc":
curl https://api2.sesamy.com/capsule/vendors/acme/.well-known/jwks.jsonSend Labrador that key in PEM format, with its kid as the key ID. Labrador then adds Sesamy as issuer sesamy for your site. Sesamy keeps the private key; it never leaves the platform.
Register Labrador's Signing Key
Register your Labrador site's domain as a trusted publisher, pointing at the signing key set Labrador publishes for the site:
curl -X PUT https://api2.sesamy.com/management/domains/www.acme.example \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{ "jwksUri": "https://www.acme.example/.well-known/labradorcms/dca/publisher-jwks.json" }'Sesamy caches the keys and picks up Labrador's key rotations automatically. A page signed for any other domain is refused.
Sign Passes and the Paywall Into the Page
Ask Labrador to include two fields in the signed resource's data object, the same fields Capsule uses:
entitlementScopes- the passes (SKUs or pass URLs) that give access to the article.paywallUrl- the article's Sesamy paywall, for login or metered access. It takes a paywall ID, a strategy ID (st_...), or the paywall's settings URL.
{
"resourceId": "article-100036",
"data": {
"entitlementScopes": ["sid:acme-plus"],
"paywallUrl": "https://api2.sesamy.com/paywall/paywalls/acme/pw_acme_metered"
}
}Without entitlementScopes, only an entitlement for the article URL opens it. Without paywallUrl, only readers with an entitlement get the keys.
API
The plugin calls POST /content/unlock with delivery: "dca":
| Field | Type | Description |
|---|---|---|
delivery | "dca" | Selects DCA delivery |
vendorId | string | Your vendor ID |
request | object | The DCA unlock request Labrador built for issuer sesamy, unchanged |
attribution | object | (Optional) Campaign attribution for paywall strategies |
shareToken | string | (Optional) A signed link token the reader arrived with for this article |
A granted request returns the content keys for Labrador:
{
"keys": {
"contentKeys": [
{ "contentName": "section-1", "key": "<base64url content key>" }
]
}
}A denied request returns 401 with "error": "denied", and the paywall when one applies.