Updating discovery to use TEI: URL

[oej]

Moving away from URN based on feedback from IETF expert group

[oej]

Discussion in meeting: Should we skip the BASE64URL encoding?

[Mehrn0ush]

Mandatory Base64 for UUID/EAN/GTIN/etc. seems to obscure identifiers that are already path-safe, so I’d propose we scope it down. For PURL (and, as noted below, SWID), some encoding is still needed when moving from urn:tei:type:domain:id (positional slots) to tei://domain/type/id (path segments), so those two are a different case.
My preference would be to avoid percent-encoding those identifiers in-path, for a few reasons:

• the percent-encoded form isn’t really any more readable than Base64 would be
• % in the identifier segment ends up double-encoded once the whole TEI is placed in /discovery?tei= (% → %25), which is a subtle failure mode
• %2F inside what’s meant to be a “single segment” is a known interop headache across CDNs, Apache, WAFs, etc.
• Base64URL, by contrast, composes cleanly when the full TEI gets URL-encoded again downstream.

So here's what I'd propose:

Type	Shape	Encoding
uuid, eanupc, gtin, asin, udi	…/<type>/<id>	Raw single leaf segment
hash	…/hash/<hashtype>/<hex>	Raw — two fixed sub-path segments (not one leaf like uuid); <hashtype> is a token from the documented list (currently SHA256/SHA384/SHA512); <hex> is the digest
purl, swid	…/<type>/<id>	BASE64URL without = padding of the canonical UTF-8 identifier string; decoders should accept unpadded input (re-pad to a multiple of 4 before decoding, or accept both padded and unpadded forms)

I looked into NISTIR 8060 to check whether tagId could safely be treated as raw. It turns out @regid is explicitly defined there as an RFC 3986 URI, but @tagId isn’t given any documented character restriction — and NIST’s own multi-language example in §4.3 actually uses a tagId with a literal space and non-ASCII characters (jp.largecomputerco.タグ番号 1). So if TEA’s swid type ends up embedding a tagId (or similar free-text SWID identifier), I don’t think we can assume it’s path-safe, and it’d probably be safer to give it the same Base64URL treatment as PURL rather than passing it through raw.

Curious what others think.

[oej]

I don't have access to the SWID ISO standard but it seems complex to include an XML document into a URL... Anyone that knows more? Is there a simplified tag we can use to indicate a product release?

[oej]

I've removed BASE64URL on everything except PURLs now. Thanks for the feedback @Mehrn0ush

[Mehrn0ush]

Good question — TEI doesn't put a SWID XML document in the URL.

In the discovery readme, the swid type works like uuid or purl: one identifier string in urn:tei:swid:<domain-name>:<swid>, not an XML blob. The obvious thing to put there is the SWID @tagId — the short unique ID every tag already has (NISTIR 8060 has examples like com.acme.rms-ce-v4-1-5-0). The full SWID tag, or CoSWID on constrained devices, would be something you fetch after discovery, not something embedded in the TEI itself.

One follow-up on the latest push, though: since db2a754 removes BASE64URL from everything except PURL, swid is now in the "raw" bucket too. I don't think that's safe — @tagId has no documented character restriction, and NIST's own §4.3 example includes a space and non-ASCII characters (jp.largecomputerco.タグ番号 1). So swid probably needs to stay alongside purl with BASE64URL, not join the raw group.

Also, the readme doesn't explicitly say <swid> = bare @tagId — worth pinning that down in the same pass.

And unrelated to all this: the readme already notes there's a TEI-native swid type and a separate PURL SWID form (pkg:swid/...) — easy to conflate, worth keeping distinct.

[oej]

RIght, I did not touch SWID because I had no example. I can do that now.

[taleodor]

Some inconsistency issues:

• The only end-to-end /discovery examples don't follow the new grammar. One mixes a literal <domain-name> placeholder with URN-style colons and then encodes to a different string than it shows; the other glues a URN body onto a tei:// prefix with the PURL raw, although the text above makes BASE64URL mandatory for PURL.
• The UUID example appears in three renderings: raw in the UUID section, BASE64URL in the DNS overview, raw again in the TLS section. The text says UUIDs are raw.
• 404 is overloaded. The new error-handling section defines 404 as "discovery endpoint not present", while the unchanged text further down and the OpenAPI spec define a /discovery 404 as "TEI unknown". A client can't tell "fail over to the next endpoint" from "stop" -> I would recommend sticking with TEI unknown. Otherwise, let's discuss.
• The port sentence survives, but its justification (URN location-independence) was deleted, and tei://host:8443/... is now a syntactically valid authority with no stated handling.
• The rest of the repository stays on the URN form: the /discovery example in spec/openapi.yaml, the normative grammar in doc/tea-uuid-scope.md, "TEI URNs" in tea-component.md, and the {tei_urn} path in the publisher spec. The doc's own table of contents still links to the old heading.

Also some issues vs #258 that would need to be addressed:

• It says an expired token means new versions won't be accessed and should be surfaced to users. Under feat: token exchange endpoint and documentation #258 an expired access token is routine: 401 with error="invalid_token", fetch a new token, retry once. Only an expired API key is user-facing.
• The error list omits the 401 Bearer challenge, which feat: token exchange endpoint and documentation #258 makes the signal that authentication is required.
• "Validate TLS certificates" is a SHOULD here; feat: token exchange endpoint and documentation #258 says clients shall verify the server certificate.
• The touched line "sometimes with an associated authentication token" should say API key.

One pre-existing security note we can address here

Redirect handling on the .well-known/tea fetch and on /discovery is unspecified. /discovery sits under bearer auth, so a cross-origin redirect could leak the access token. #262 already states that a client never sends its token when following a redirect to a different origin; discovery should state or reference the same rule, since it's the first authenticated call.

[madpah]

Looks sane to me.

[oej]

Fixed remaining URN examples, moved some comments to issues since they need a separate PR

[oej]

Ready for re-review

[Mehrn0ush]

Lost the urn: prefix on the JWT-bearer grant type — it now reads ietf:params:oauth:grant-type:jwt-bearer instead of urn:ietf:params:oauth:grant-type:jwt-bearer. The SAML and token-exchange both still have the urn: prefix.

[oej]

Fixed in 02ef688

[oej]

@taleodor are we ready to commit this change? I need it because it's normative.

[taleodor]

Issues:

1. Line 70 (marked in code)
2. Line 303 (marked in code)
3. Line 1023 (marked in code)
4. spec/openapi.yaml:775 — the tei query parameter for /discovery, the exact endpoint this PR redefines, still carries a URN example
5. Both end-to-end /discovery examples are still wrong:
   5a. Example 1's TEI keeps a literal placeholder and a URN-style colon: tei:///uuid/products.example.com:d4d9f54a-…. The domain belongs in the authority; the identifier is just the UUID. The URL underneath then encodes a different (correct) string.
   5b. Example 2 is the sharper one. Its TEI line is now properly BASE64URL, but the URL beneath it is still the old URN body with the PURL raw: ?tei=tei%3A//products.example.com%3Apurl%3Apkg%3Adeb%2Fdebian%2Fcurl%407.50.3-1%3Farch%3Di386%26distro%3Djessie
6. TOC anchor is broken — discovery/readme.md:6 still links #the-tei-urn-an-extensible-identifier; the heading is now "The TEI: URL - An extensible identifier".
7. The IANA note was deleted, but nothing says about URI scheme registration (where TEI is registered or unregistered)
8. SWID removed, but doc/tea-requirements.md:84,92 still lists SWID as supported format
9. The UUID in example 1 is not a UUID — d4d9f54a-abcf-11ee-ac79-1a52914d44b has 11 hex digits in the last group

[taleodor]

This doesn't seem like valid TEI.

[oej]

Fixed in bc6f11e

[taleodor]

Under URL, this is valid tei://host:8443/uuid/… but based on this comment it's not clear what's the meaning here then. I think we should be more explicit about that - say that port shall not be used in TEI.

[oej]

Fixed in e3996ab

[taleodor]

this needs rewording

[oej]

Fixed 68fd1ef

[oej]

Thank you for a detailed review, it will help moving forward - I will work on this very soon.

[oej]

@taleodor The latest set of commits should fix the issues reported. Please review.

[taleodor]

Still outstanding

1. The TOC anchor is still broken. Line 6 links #the-tei-url-an-extensible-identifier, but the heading at line 75 is ## The TEI: URL - An extensible identifier, whose GitHub slug is the-tei-url---an-extensible-identifier — the " - " produces three hyphens. Line 5 of the same TOC gets this right (#tea-discovery---defining-an-extensible-identifier).

2. Example 2's URL is still the URN form. Line 336:

?tei=tei%3A//products.example.com%3Apurl%3AcGtnOmRlYi9kZWJpYW4v…

That decodes to products.example.com:purl: — colons rather than /purl/. The TEI on line 335 above it is now correct, so the example contradicts itself.

3. The truncated UUID survives in the /discovery examples. Lines 333–334 still carry d4d9f54a-abcf-11ee-ac79-1a52914d44b — 11 hex digits in the final group. Lines 163 and 399 have the correct …44b1, and eafdaa07 fixed openapi.yaml, but these two were missed.

4. Scheme registration, and a now-misleading reference. Line 405 reads "[IANA URI registry]" but links to assignments/urn-namespaces/…#urn-namespaces-1, the URN namespaces registry. With TEI no longer a URN that link is stale and the label does not match its target. If tei:// is to be registered, that is RFC 7595 and the URI schemes registry — worth stating somewhere, since the note about registering the URN namespace was removed in this PR.

New in the latest commits

5. spec/openapi.yaml: - latestCollection gained a trailing space. Pure churn, and the sort of thing a YAML linter flags.

[oej]

Fixed issues.

Not adding a comment about URL schema at this point, that's for after 1.0. Will make sure we have an issue

[taleodor]

Let's merge this.