Add the 51Did creator context web example

[jwrosewell]

The 51Did creator context feature in two parts, being the web example that shows the flow and the cloud client in pipeline.did that the example's server now uses.

The creator context web example

Adds pipeline.developer-examples/pipeline.developer-examples.fodid's CreatorContextDemoServer, a small server on the JDK's own web server that serves page.html. The page creates a 51Did in the browser through the cloud json endpoint, verifies it from the browser with verify-full (which answers with a sealed result the browser cannot read or forge), and hands the sealed result to the server's /redeem route, which redeems it with the licence key the browser never sees. Once the identifier validates, the page offers a link carrying the same 51Did, and opening that link in another browser shows the signature still verifying while the creator context does not, which is the copied identifier caught at presentation. The same commit lets every example that calls the cloud be pointed at another host through FOD_CLOUD_API_URL, the variable the cloud request engine already honours, with the resource key from _51DEGREES_RESOURCE_KEY. The cloud engine example reads both (falling back to the star sign service it was written for) and reports plainly when the host offers no star sign product, and the root README describes the variables.

The cloud client, used by the example

pipeline.did gains DidClient, one type for everything a server does with a 51Did against the 51Degrees cloud, so server code never hand-writes HTTP or key handling. New public surface:

• FodId.fromBase64 now accepts the URL-safe base64 alphabet (-, _, padding optional) as well as the standard one the cloud issues, normalising before the OWID library sees it, because that library's decoder ignores characters outside the standard alphabet rather than refusing them. Whitespace around the value is stripped at the same point, so an identifier read from a header, a file or a form field with a newline or a space around it reads as the same identifier as the clean form, and the base64 padding is worked out from the stripped length. FodId.asBase64Url() gives the URL-safe form without padding, and FodId.getDateMinutes() gives the envelope's own date field, the unsigned count of minutes since 2020-01-01T00:00:00Z. getLicenseId() is documented as the raw field, which on an identifier carrying a creator context holds an encrypted value only 51Degrees can read. The minimum length rule is unchanged.
• DidClient(resourceKey), DidClient(resourceKey, licenceKey), DidClient(resourceKey, licenceKey, endpoint) and DidClient.builder(resourceKey) (which also takes an HttpTransport and a Clock). The endpoint defaults to https://cloud.51degrees.com/api/v4/, or FOD_CLOUD_API_URL where set, and a trailing slash is added where missing.
• publicKeys() fetches GET id/key/{resource} once and holds the list, reading startsAt (or the compatibility field created when startsAt is absent) and publicKey. publicKeyFor(fodId) returns the key in force at the identifier's date, refetching once when the held list has no key for the date, when the date is later than the newest start held, or when the list is more than a day old. A required refresh failure propagates because the held schedule may not contain the correct key.
• verifySignature(fodId) and verifySignatureDetailed(fodId) check the signature offline the way the cloud's verify endpoint does: version 3 only, the payload at least the base length for its type (a longer payload carries a creator context section and is accepted), and the key in force at the identifier's date plus the neighbouring key within the cloud's tolerance either side of a boundary, never every earlier key.
• verify(fodId) calls GET id/verify/{resource}?51did= and returns the cloud's valid, raising IllegalArgumentException with the cloud's message for a value that is not a 51Did. The identifier is sent under both parameter names, 51did and owid, so the request works with hosts that read either parameter. Hosts that recognise both prefer 51did and keep owid as a compatibility alias.
• redeem(fodId, result, challenge) sends POST id/redeem (the bare path, because the POST route carries no resource segment) with resource, 51did, result, challenge and license in the form body (neither key is ever in a URL) and returns a typed RedeemResult for a 200 or 503 answer: Context (VERIFIED, MISMATCH, NO_CONTEXT, NOT_CHECKABLE, EXPIRED, REPLAYED, UNREADABLE, UNCONFIRMED, with any unknown word mapped to UNREADABLE and kept in getContextValue()), Signature (VERIFIED, INVALID, UNKNOWN), getFactors() when the cloud sent them, getVerifiedAt(), getSecondsSinceVerified(), getStatusCode() and getRaw(). A 400 raises IllegalArgumentException, a 404 raises DidNotSupportedException (the host does not offer the creator context), any other status raises DidHttpException with the status and body, and an unreachable host raises IOException.
• HttpTransport, an interface over HttpURLConnection with Request and Response types, so tests inject the network. SigningKey is one entry of the key list.

Every request carries a User-Agent of pipeline.did/{version} from the jar manifest. The package adds org.json:json at the version pipeline.cloudrequestengine already uses, so the pipeline carries no new dependency. Everything compiles at the Java 8 level and Animal Sniffer checks the API.

The example's /redeem route (CreatorContextDemoServer.redeem) now builds one DidClient at start-up, parses the incoming 51Did with FodId.fromBase64, calls verifySignature, then redeem, and answers the page in the cloud's own shape (signature, context, factors when present, verifiedAt, secondsSinceVerified) with one field added, serverSignature. page.html is unchanged. A host without the creator context still answers 404 with a text body, which the page reports as not supported by this host, and an unreachable cloud answers 502 with { "error": ... }. The example readme's copy-these-lines section shows the client calls, and the package readme gains a "Verifying on your server" section covering parse, offline verify, cloud verify and redeem, with a note that verify-context and verify-full are browser calls because the context describes the browser's own connection.

Tests

Unit tests use the injected transport and a real ECDSA key pair, with no network. They cover both base64 alphabets and the round trip, getDateMinutes, the key list (startsAt, the created fallback, cache hit, each refetch rule and a failed required refresh with an injected clock), key selection at and around a boundary, offline verification (right key, wrong key, version 2, short payload, payload with a context section, a long context section signed with a longer creator domain, random identifier), cloud verification (200 valid, 400 invalid, 400 errors), and every redeem outcome including 503, 400, 404, an unknown context word, the form fields, and the licence key's absence from the URL. The example's route is tested for the cloud's shape with serverSignature, factors, 503, 404, 502 and 400. Two live tests run only when _51DEGREES_RESOURCE_KEY is set and are skipped otherwise. Further tests cover an identifier arriving with a leading space, a trailing space or a trailing newline in either alphabet, a long creator context section and a longer creator domain reading back through every factory, and the client turning away an over-long encoded value through both its string and its object entry points without making a request.

Module	Before	After
pipeline.did	32 run, 0 failed	99 run, 0 failed, 2 skipped (live tests without a resource key)
pipeline.developerexamples.fodid	1 run, 0 failed	9 run, 0 failed

Both modules build, with mvn -pl pipeline.did -am test and mvn -pl pipeline.developer-examples/pipeline.developer-examples.fodid -am package.

Identifier size is left to the cloud

The package states no maximum length for a 51Did, and the reader keeps only the lower bound it has always had, which is that a payload must be at least the base length for its identifier type. Anything longer is accepted and left to the cloud to judge. Two reasons make a fixed maximum in the package wrong. The creator domain is a deployment parameter, so a self-hosted container may sign with a longer domain than the cloud does and its identifiers must still parse. The service also accepts a creator context section of a version it does not implement at any length, which is what lets an older verifier keep working when a newer version ships, and the package has to behave the same way.

DidClient keeps one generous bound so it does not do work on input that cannot be an identifier at all. An encoded identifier longer than 4096 characters is refused before the client decodes it, fetches a key or calls the cloud. That figure is arbitrary and far above anything the cloud issues, and its only job is to turn away obviously malformed input. Public method signatures are unchanged, and cloud response bodies are not capped by any of this.