Entitlement Certificate Contract v1

Contract: stella.ops/entitlementCertificate@v1 (CONTRACT-ENTITLEMENT-CERTIFICATE-V1-072). Schema: entitlement-certificate.v1.schema.json (JSON Schema 2020-12, the payload). DSSE payload type: application/vnd.stellaops.entitlement-certificate.v1+json. Signature algorithm: ES256 (ECDSA P-256 with SHA-256; the signature is the 64-byte r || s concatenation). Examples: valid payload, invalid payload. Sprint: SPRINT_20261027_004 ENT-2. Import and storage: ENT-4. Implementation: src/__Libraries/StellaOps.Entitlements/ (EntitlementVerifier, EntitlementCertificateParser, EntitlementTrustRoot, IEntitlementTrustRootSource); tests in src/__Libraries/__Tests/StellaOps.Entitlements.Tests/, which also hold the published examples and schema to this contract. Posture: advisory only; see the Platform dossier, Installation entitlements: advisory posture.

Purpose

An entitlement certificate is a record, signed by the Licensor, of the production-use placement capacity authorised for one Installation under an accepted order, for a stated period. An operator imports it into the Installation and can verify it at any time without a connection to Stella Ops.

The certificate evidences capacity. It never enforces it: expiry, or a placement count above the authorised capacity, produces status and warnings only. Deployments, scans, evidence and running workloads are never blocked by it.

What a valid certificate establishes

A certificate that verifies against a pinned vendor root establishes, and only establishes:

• that the Licensor named in issuer signed this payload with the key issuerKeyId;
• that the order orderReference authorises customerOrganisation to manage up to authorisedPlacements active placements in the Installation installationId, for the use permittedUse, from validFrom until validTo;
• that this is revision revision of the subscription serial.

It does not establish:

• that any placement was actually deployed, gated, promoted or scanned, or how many;
• that scans ran correctly, that every workload was inspected, or that any finding, policy decision or evidence package is correct or complete;
• the security posture of anything the Installation manages, or compliance with any regulation;
• that an Installation without a certificate, or with an expired one, is unlicensed: the free allowance and other permissions of the LICENSE apply independently.

Its expiry does not disable delivered software or customer workloads, and does not withdraw the authorisation it recorded for its own period. Billing expiry is separate from key compromise: an expired certificate remains a valid record of its term.

Envelope

The certificate is a DSSE envelope (JSON):

{
  "payloadType": "application/vnd.stellaops.entitlement-certificate.v1+json",
  "payload": "<base64 of the canonical payload bytes>",
  "signatures": [
    { "keyid": "<issuerKeyId>", "sig": "<base64 of the ES256 signature>" }
  ]
}

• payload is the standard base64 encoding of the payload’s RFC 8785 canonical JSON bytes. A payload that is not byte-identical to its own canonical form is refused.
• Each signature covers the DSSE pre-authentication encoding PAE(payloadType, payload bytes) = "DSSEv1" SP len(type) SP type SP len(payload) SP payload.
• The envelope verifies when at least one signature verifies under a pinned vendor root whose key identifier equals that signature’s keyid and the payload’s issuerKeyId. A signature under any other key is ignored; an envelope with no verifying signature is refused.
• Certificates are exchanged as files (.dsse.json); import and verification need no network.

Payload fields

All fields are required, and no other field is allowed.

Verification rules

A verifier holds only vendor public roots. It refuses, with a stated reason:

1. an envelope that is not valid JSON, has a payload type other than the one above, or has no signature;
2. a payload that is not canonical JSON, does not match the schema, or has validTo not later than validFrom;
3. an envelope with no signature that verifies under a pinned vendor root, including a signature by an unknown key identifier or a key identifier that differs from issuerKeyId;
4. a certificate whose installationId is not the verifying Installation’s identifier;
5. a revision lower than the highest revision of the same serial that the Installation already accepted, or an equal revision whose payload bytes differ from the accepted one (rollback). An equal revision with identical bytes is the same certificate imported again;
6. any input that contains private key material where a public root is expected.

A certificate past validTo still verifies: it is reported as expired, not as invalid. Verification fails closed: an error in any step refuses the certificate.

Supersede rules

• One subscription keeps one serial. Renewal, a capacity change, a change of organisation name and reissue for another Installation are new revisions of that serial.
• Within one serial, the highest accepted revision is the current one, and it replaces every lower revision completely: its period, capacity and installation are the ones that count. The issuer therefore gives a renewal revision a period that covers the time it is meant to cover.
• A revision lower than the highest accepted revision of its serial is refused, and so is a different payload under an already accepted revision, so a superseded revision can never be brought back. Importing the same certificate again changes nothing.
• Separate serials are separate subscriptions for the same Installation. The authorised capacity of the Installation is the sum of the current revisions of its serials that are within their period.

Examples

• examples/entitlement-certificate.v1.valid.json is a payload that matches the schema.
• examples/entitlement-certificate.v1.invalid.json is refused: its installationId is not lowercase, authorisedPlacements is 0, and it carries a field the contract does not define.

The examples are payloads only. A real certificate is signed by the vendor entitlement key, which is never present in the product or in this repository; tests sign with ephemeral keys they generate.