DOC: 51Did factor outcomes and the public key list as released

[jwrosewell]

Aligns the 51Did page (src/identifiers/fodid.md) to the 51Did verification and public key behaviour of cloud release 4.4.45 and the 51Did packages released with it.

What was wrong

• The factor block was described as sent only where context is mismatch or misconfigured with some factors compared, and each factor as one of three values. The service reports four values, verified, mismatch, misconfigured and notrecorded, and sends the block whenever any factor is notrecorded, whatever the overall result, so a verified context can sit beside notrecorded factors.
• The public key section pointed at GET /owid/api/v3/creator with a publicKeySPKI field. That endpoint answers 404 on production and the OWID key endpoint is GET /owid/api/v3/public-key, answering { format, publicKey, validFrom, validTo }.
• The key list example showed only created and publicKey, described the datetime filter as selecting on created, and said the endpoint needed a Resource Key. Each entry carries startsAt, endsAt, created and publicKey, the filter selects keys whose period starts at or after the timestamp, and a licence key alone is accepted.
• The local verification option told readers to fetch one key and cache it, and the readers table had no Rust package.

What it now says

• Each factor is verified, mismatch, misconfigured or notrecorded. notrecorded means the creator recorded no value, so the factor took no part in context, and factors is sent on a mismatch, on a misconfigured result that still compared some factors, and whenever any factor is notrecorded. A verified context beside notrecorded factors rests on the factors that were recorded.
• GET /api/v4/id/key/{resource} (or a licence key as license) publishes every key whose period has started plus the next key in the fifteen minutes before its start. Each entry carries startsAt, endsAt (the next key's start, carried by the newest entry although the next key is not published), created and publicKey. A key may be replaced before its endsAt. datetime is read as UTC and selects keys starting at or after it. The answer is cached privately for at most 1800 seconds and never past the next publication, and a refusal is never cached.
• The client in each package holds the list and verifies offline every 51Did dated before the newest endsAt held, fetches only for an identifier dated at or after that less the fifteen minute allowance, at most once a minute, fetches the whole list again once it is a day old, and after a failed signature fetches once more from the start of the key in force at the identifier's date before reporting a failure.
• GET /owid/api/v3/public-key?date=<minutes> returns the one key in force at date with validFrom and validTo, takes the same credentials and is metered.
• The readers table lists fodid-client for Rust.

What the wording matches

Cloud release 4.4.45, live on production, and the 51Did packages fiftyone.pipeline.did 4.5.51 (npm), fiftyone-pipeline-did 4.5.31 (PyPI), com.51degrees:pipeline.did 4.5.40 (Maven Central), FiftyOne.Did 4.5.116 (NuGet), 51degrees/fiftyone.pipeline.did 4.5.1 (Packagist) and fodid-client 4.5.7-9 (crates.io).

Checked against the cloud source at tag 4.4.45 (Controllers/FodId/KeyController.cs, Controllers/FodId/RedeemController.cs, Helpers/ContextVerifier.cs, Keys/Data/KeySchedule.cs, Controllers/OwidApi/PublicKeyController.cs), the .NET, Node and Rust clients on their main branches, and production, where /owid/api/v3/creator answers 404 and /owid/api/v3/public-key and /api/v4/id/key answer 401 with Cache-Control: no-store without a credential. The shared 51degrees.com link lint passes with this repository's forbid mode.

[github-actions]

Documentation preview 👀