tshex-cli 1.0.27 → 1.0.29

package/docs/shared/application/http/json-api.md

@@ -0,0 +1,235 @@
+### JSON:API
+
+`json-api.ts` declares a type-only implementation of the
+[JSON:API v1.1](https://jsonapi.org/format/) specification, including the
+[Atomic Operations extension](https://jsonapi.org/ext/atomic/). It gives an
+adapter a shared vocabulary for request and response bodies without forcing a
+particular server framework.
+
+This module has no runtime code. It only describes compile-time structure;
+rules that depend on runtime values, URI validity, document-wide uniqueness,
+full linkage, HTTP semantics, or member-name character validation still
+require explicit checks in the adapter.
+
+#### Resource Identifiers
+
+A resource is referenced in one of two ways, depending on whether the server
+has assigned it a permanent id yet.
+
+| Type | Option | Required members |
+| --- | --- | --- |
+| `JsonApiPersistedResourceIdentifier` | Server-assigned id | `type`, `id` |
+| `JsonApiLocalResourceIdentifier` | Client-assigned local id, not yet persisted | `type`, `lid` |
+
+`JsonApiResourceIdentifier` is the union of both.
+
+```ts
+import type { JsonApiResourceIdentifier } from '../../../shared/application/http/json-api.js'
+
+const persisted: JsonApiResourceIdentifier<'users'> = { type: 'users', id: '1' }
+const local: JsonApiResourceIdentifier<'users'> = { type: 'users', lid: 'tmp-1' }
+```
+
+Resource linkage (`JsonApiResourceLinkage`) is either a single identifier or
+`null` (`JsonApiToOneLinkage`), or an array of identifiers
+(`JsonApiToManyLinkage`).
+
+#### Resource Objects
+
+A resource object has the same persisted-versus-local split as its
+identifier.
+
+| Type | Option | `id` | `lid` |
+| --- | --- | --- | --- |
+| `JsonApiResourceObject` | Server-originated resource | required | optional |
+| `JsonApiNewResourceObject` | Client-originated resource without a server id | never | optional |
+
+`JsonApiCreateResourceObject` is the union accepted by create requests, since
+a client is allowed to submit a client-generated id.
+
+```ts title="users/adapters/get-user-handler.ts"
+import { HttpRequestHandler } from '../../shared/application/http/handlers.js'
+import {
+    JsonApiSingleResourceDocument,
+    JsonApiResourceObject,
+} from '../../shared/application/http/json-api.js'
+
+type UserAttributes = { email: string }
+type UserResource = JsonApiResourceObject<'users', UserAttributes>
+
+export class GetUserHandler implements HttpRequestHandler {
+    public handle(request: Request): Response {
+        const id = new URL(request.url).pathname.split('/').at(-1) ?? ''
+
+        const body: JsonApiSingleResourceDocument<UserResource> = {
+            data: {
+                type: 'users',
+                id,
+                attributes: { email: 'ada@example.com' },
+            },
+        }
+
+        return Response.json(body, { status: 200 })
+    }
+}
+```
+
+#### Relationships
+
+`JsonApiRelationship` requires at least one of `links`, `data`, or `meta`, per
+the base specification. Two narrower aliases fix the shape of `data`:
+
+| Type | `data` shape |
+| --- | --- |
+| `JsonApiToOneRelationship` | single identifier or `null` |
+| `JsonApiToManyRelationship` | array of identifiers |
+
+```ts
+import type {
+    JsonApiToOneRelationship,
+    JsonApiToManyRelationship,
+} from '../../../shared/application/http/json-api.js'
+
+const author: JsonApiToOneRelationship<{ type: 'authors' }> = {
+    data: { type: 'authors', id: '9' },
+}
+
+const comments: JsonApiToManyRelationship<{ type: 'comments' }> = {
+    data: [{ type: 'comments', id: '1' }, { type: 'comments', id: '2' }],
+}
+```
+
+#### Documents
+
+`JsonApiDocument` is a discriminated union over which top-level member is
+required. Exactly one of these three shapes is valid at a time:
+
+| Type | Required top-level member | Use |
+| --- | --- | --- |
+| `JsonApiDataDocument` | `data` | success responses returning resources |
+| `JsonApiErrorDocument` | `errors` (non-empty) | failure responses |
+| `JsonApiMetaDocument` | `meta` | responses with no primary data, such as a heartbeat |
+
+`JsonApiDataDocument` itself is narrowed by four ready-made aliases depending
+on what `data` contains:
+
+| Alias | `data` shape |
+| --- | --- |
+| `JsonApiSingleResourceDocument` | resource or `null` |
+| `JsonApiResourceCollectionDocument` | array of resources |
+| `JsonApiSingleIdentifierDocument` | identifier or `null` |
+| `JsonApiIdentifierCollectionDocument` | array of identifiers |
+| `JsonApiRelationshipDocument` | any resource linkage |
+
+```ts
+import type {
+    JsonApiErrorDocument,
+    JsonApiMetaDocument,
+} from '../../../shared/application/http/json-api.js'
+
+const notFound: JsonApiErrorDocument = {
+    errors: [{ status: '404', title: 'Not Found' }],
+}
+
+const heartbeat: JsonApiMetaDocument<{ status: string }> = {
+    meta: { status: 'ok' },
+}
+```
+
+#### Request Documents
+
+Three request-only document shapes fix `data` to exactly what each operation
+accepts:
+
+| Type | `data` shape | Use |
+| --- | --- | --- |
+| `JsonApiCreateDocument` | `JsonApiCreateResourceObject` | `POST` requests |
+| `JsonApiUpdateDocument` | `JsonApiResourceObject` | `PATCH` requests |
+| `JsonApiRelationshipUpdateDocument` | resource linkage | relationship endpoints |
+
+`JsonApiQueryParameters` describes the standard `include`, `sort`, `filter`,
+and `page` query members, plus the `fields[TYPE]`, `filter[FIELD]`, and
+`page[FIELD]` bracketed member-name patterns.
+
+#### Errors
+
+`JsonApiError` requires at least one of `id`, `links`, `status`, `code`,
+`title`, `detail`, `source`, or `meta`.
+
+```ts
+import type { JsonApiError } from '../../../shared/application/http/json-api.js'
+
+const validationError: JsonApiError = {
+    status: '422',
+    title: 'Invalid Attribute',
+    detail: 'email must be a valid address',
+    source: { pointer: '/data/attributes/email' },
+}
+```
+
+#### Atomic Operations Extension
+
+The Atomic Operations extension adds a request document that carries one or
+more operations, and a response document that carries their results. Every
+operation targets either a resource or a relationship, and every operation
+uses exactly one of three op codes. `JsonApiAtomicStrictOperation` is the
+union of the seven concrete shapes that combination produces:
+
+| Type | `op` | Target | `data` |
+| --- | --- | --- | --- |
+| `JsonApiAtomicAddResourceOperation` | `'add'` | resource (`ref` optional, `href` optional) | resource to create |
+| `JsonApiAtomicUpdateResourceOperation` | `'update'` | resource | resource to replace |
+| `JsonApiAtomicRemoveResourceOperation` | `'remove'` | resource (required) | none |
+| `JsonApiAtomicUpdateToOneRelationshipOperation` | `'update'` | relationship (required) | identifier or `null` |
+| `JsonApiAtomicAddToManyRelationshipOperation` | `'add'` | relationship (required) | identifier array |
+| `JsonApiAtomicUpdateToManyRelationshipOperation` | `'update'` | relationship (required) | identifier array |
+| `JsonApiAtomicRemoveFromManyRelationshipOperation` | `'remove'` | relationship (required) | identifier array |
+
+A target is expressed through `ref` (a `JsonApiAtomicResourceRef` or
+`JsonApiAtomicRelationshipRef`) or through `href`, never both at once
+(`JsonApiExclusive`).
+
+```ts title="users/adapters/atomic-operations-handler.ts"
+import {
+    JsonApiAtomicOperationsDocument,
+    JsonApiAtomicResultsDocument,
+    JsonApiAtomicStrictOperation,
+} from '../../shared/application/http/json-api.js'
+
+const request: JsonApiAtomicOperationsDocument<JsonApiAtomicStrictOperation> = {
+    'atomic:operations': [
+        { op: 'add', href: '/users', data: { type: 'users', attributes: { email: 'ada@example.com' } } },
+        { op: 'update', ref: { type: 'users', id: '1' }, data: { type: 'users', id: '1', attributes: { email: 'ada@lovelace.dev' } } },
+        { op: 'remove', ref: { type: 'users', id: '2' } },
+        { op: 'update', ref: { type: 'users', id: '1', relationship: 'team' }, data: { type: 'teams', id: '9' } },
+        { op: 'add', ref: { type: 'teams', id: '9', relationship: 'members' }, data: [{ type: 'users', id: '1' }] },
+    ],
+}
+
+const response: JsonApiAtomicResultsDocument = {
+    'atomic:results': [{ data: { type: 'users', id: '1' } }, {}, {}, {}, {}],
+}
+```
+
+`JsonApiAtomicRequestDocument` and `JsonApiAtomicResponseDocument` are the
+named aliases for the request and response side of the extension; the latter
+is a union of `JsonApiAtomicResultsDocument` and `JsonApiErrorDocument`, since
+a batch of operations can still fail as a whole.
+
+#### Extension And `@`-Members
+
+`JsonApiExtensionMembers` and `JsonApiAtMembers` compose extension-namespaced
+(`'ext:member'`) and meta (`'@member'`) properties through intersections, for
+custom or third-party JSON:API extensions beyond Atomic Operations.
+
+```ts
+import type { JsonApiExtensionMembers, JsonApiResourceObject } from '../../../shared/application/http/json-api.js'
+
+type VersionedResource = JsonApiResourceObject<'users'> &
+    JsonApiExtensionMembers<'version', { id: string }>
+```
+
+> **Hint**
+> These declarations only provide compile-time structure. Rules that depend on
+> runtime values, URI validity, document-wide uniqueness, or member-name
+> character validation still require explicit checks in the adapter.

package/docs/shared/application/http/json-web-token.md

@@ -0,0 +1,209 @@
+### JSON Web Tokens
+
+`json-web-token.ts` declares a type-only implementation of the JOSE and JWT
+family of RFCs (JWS, JWE, JWK, JWT, and related extensions such as DPoP and
+selective disclosure). It lets an adapter describe tokens and keys precisely
+without depending on a specific JOSE library's own types.
+
+This module has no runtime implementation. Pair it with a concrete JOSE
+library (for signing, encryption, or verification) and use these types to
+annotate its inputs and outputs.
+
+#### Branded Wire Values
+
+Wire-format primitives are branded so a plain `string` cannot be passed where
+an encoded value is expected: `Base64Url`, `Base64`, `NumericDate`,
+`StringOrURI`, `UriString`, `MediaType`, and `KeyId`. `BinaryData` is the
+union `ArrayBuffer | Uint8Array` used wherever a JOSE library accepts raw
+bytes.
+
+#### JSON Web Keys
+
+Every JWK shares `JwkCommonParameters` (`kty`, `use`, `key_ops`, `alg`, `kid`,
+the `x5*` certificate members, and the OpenID Federation `iat`/`nbf`/`exp`/
+`revoked` members). `JwkKeyType` (`kty`) then selects one of five key-family
+options, each with a public and a private variant where the family supports
+one:
+
+| `kty` | Curve/size parameter | Public type | Private type |
+| --- | --- | --- | --- |
+| `'EC'` | `EcCurve` (`P-256`, `P-384`, `P-521`, `secp256k1`) | `EcPublicJwk` (`x`, `y`) | `EcPrivateJwk` (adds `d`) |
+| `'RSA'` | — | `RsaPublicJwk` (`n`, `e`) | `RsaPrivateJwk` (adds `d`, `p`, `q`, `dp`, `dq`, `qi`, `oth`) |
+| `'oct'` | — | — (symmetric only) | `OctJwk` (`k`) |
+| `'OKP'` | `OkpCurve` (`Ed25519`, `Ed448`, `X25519`, `X448`) | `OkpPublicJwk` (`x`) | `OkpPrivateJwk` (adds `d`) |
+| `'AKP'` | `MldsaAlgorithm` (`ML-DSA-44`/`65`/`87`) | `AkpPublicJwk` (`pub`) | `AkpPrivateJwk` (adds `priv`) |
+
+`PublicJwk` and `PrivateJwk` are the unions across all five families;
+`JsonWebKey` is `PublicJwk | PrivateJwk`.
+
+```ts
+import type { EcPublicJwk, RsaPrivateJwk, OctJwk } from '../../../shared/application/http/json-web-token.js'
+
+const ecKey: EcPublicJwk = { kty: 'EC', crv: 'P-256', x: '...' as Base64Url, y: '...' as Base64Url }
+const rsaKey: RsaPrivateJwk = { kty: 'RSA', n: '...' as Base64Url, e: '...' as Base64Url, d: '...' as Base64Url }
+const symmetricKey: OctJwk = { kty: 'oct', k: '...' as Base64Url }
+```
+
+`JsonWebKeySet` wraps a `keys` array of mixed key types; `PublicJsonWebKeySet`
+narrows that array to public keys only, for a key set safe to publish. A
+thumbprint (`JwkThumbprint`) is a `Base64Url`; `JwkThumbprintUri` is the
+`urn:ietf:params:oauth:jwk-thumbprint:` URI form.
+
+#### Headers
+
+`JoseCommonHeaderParameters` covers the parameters shared by both header
+kinds (`jku`, `jwk`, `kid`, the `x5*` members, `typ`, `cty`, `crit`).
+`JwsHeaderParameters` and `JweHeaderParameters` extend it with the two
+distinct options:
+
+| Type | Required members | Extra members |
+| --- | --- | --- |
+| `JwsHeaderParameters` | `alg: JwsAlgorithm` | `b64`, `ppt`, `url`, `nonce`, `svt`, `jwt`, `client_id`, `trust_chain`, `peer_trust_chain` |
+| `JweHeaderParameters` | `alg: JweKeyManagementAlgorithm`, `enc: JweContentEncryptionAlgorithm` | `zip`, `epk`, `apu`, `apv`, `iv`, `tag`, `p2s`, `p2c`, replicated `iss`/`sub`/`aud`, `url`, `nonce` |
+
+`JwsHeader<CustomHeader>` and `JweHeader<CustomHeader>` intersect the
+respective parameters with a caller-supplied custom header shape.
+
+#### Serializations
+
+A JWS or a JWE can be represented four ways: as a single delimited string
+(compact), or as JSON with either one signer/recipient inlined (flattened) or
+several (general).
+
+| Type | Kind | Shape |
+| --- | --- | --- |
+| `CompactJws` | JWS, compact | `` `${string}.${string}.${string}` `` branded string |
+| `GeneralJwsJsonSerialization` | JWS, JSON, general | `payload` + `signatures[]` |
+| `FlattenedJwsJsonSerialization` | JWS, JSON, flattened | `payload` + one signature inlined |
+| `CompactJwe` | JWE, compact | `` `${string}.${string}.${string}.${string}.${string}` `` branded string |
+| `GeneralJweJsonSerialization` | JWE, JSON, general | shared members + `recipients[]` |
+| `FlattenedJweJsonSerialization` | JWE, JSON, flattened | shared members + one recipient inlined |
+
+`JwsJsonSerialization` and `JweJsonSerialization` are the general/flattened
+unions for each. `UnsecuredCompactJws` types the `alg: 'none'` compact form
+(`` `${string}.${string}.` `` — an empty signature segment).
+
+```ts
+import type { CompactJws, FlattenedJwsJsonSerialization } from '../../../shared/application/http/json-web-token.js'
+
+const compact = 'eyJhbGciOiJFUzI1NiJ9.eyJzdWIiOiIxIn0.c2ln' as CompactJws
+
+const flattened: FlattenedJwsJsonSerialization = {
+    payload: 'eyJzdWIiOiIxIn0' as Base64Url,
+    protected: 'eyJhbGciOiJFUzI1NiJ9' as Base64Url,
+    signature: 'c2ln' as Base64Url,
+}
+```
+
+`DecodedJws` and `DecodedJwe` describe a decoded token's structure;
+`DecodedJwt` is their union, discriminated by a `kind: 'JWS' | 'JWE'` tag.
+`CompactJwt` is `CompactJws | CompactJwe`, matching how RFC 7519 allows a JWT
+to use either serialization.
+
+#### JWT Claims
+
+`JwtRegisteredClaims` covers the seven RFC 7519 claims (`iss`, `sub`, `aud`,
+`exp`, `nbf`, `iat`, `jti`). `IanaRegisteredJwtClaims` extends it with every
+claim name currently registered by IANA (OpenID Connect profile claims, SIP,
+CDNI, GNAP, EAT, RATS, RFC 9901 selective-disclosure claims, OpenID
+Federation claims, and more), so `JwtClaims<CustomClaims>` covers arbitrary
+custom claims through intersection while still typing every standard one.
+
+Four ready-made profiles fix `JwtRegisteredClaims` members to `required`
+where the profile mandates them, as distinct implementation options for
+common token kinds:
+
+| Type | Profile | Required beyond the base seven |
+| --- | --- | --- |
+| `OpenIdConnectIdTokenClaims` | OIDC ID Token | `iss`, `sub`, `aud`, `exp`, `iat` |
+| `OAuth2JwtAccessTokenClaims` | RFC 9068 OAuth 2.0 access token | `iss`, `exp`, `aud`, `sub`, `client_id`, `iat`, `jti` |
+| `DpopProofClaims` | RFC 9449 DPoP proof | `jti`, `htm`, `htu`, `iat` |
+| `SdJwtClaims` | RFC 9901 SD-JWT | none beyond `IanaRegisteredJwtClaims`, adds `_sd`/`_sd_alg` |
+
+```ts title="users/adapters/verify-access-token.ts"
+import {
+    JwsVerifier,
+    OAuth2JwtAccessTokenClaims,
+    CompactJws,
+    JsonWebKey,
+} from '../../shared/application/http/json-web-token.js'
+
+export function verifyAccessToken(
+    verifier: JwsVerifier,
+    token: CompactJws,
+    key: JsonWebKey,
+) {
+    return verifier.verify<OAuth2JwtAccessTokenClaims>(token, key)
+}
+```
+
+`SdJwtDisclosure`, `SdJwt`, and `SdJwtPresentation` brand the three distinct
+string forms used by selective disclosure: a single disclosure, an issued
+SD-JWT, and a presentation with disclosures appended.
+
+#### Service Contracts
+
+An adapter implements these interfaces against a concrete JOSE library. Each
+one exposes a distinct operation:
+
+| Contract | Method(s) | Responsibility |
+| --- | --- | --- |
+| `JwtDecoder` | `decode()` | Parse a compact token into a `DecodedJwt` without necessarily validating it. |
+| `JwsSigner` | `signCompact()`, `signFlattened()` | Produce a JWS in either serialization. |
+| `JwsVerifier` | `verify()` | Validate a JWS and return a `JwtValidationResult`. |
+| `JweEncrypter` | `encryptCompact()`, `encryptFlattened()` | Produce a JWE in either serialization. |
+| `JweDecrypter` | `decrypt()` | Decrypt a JWE back into `BinaryData`. |
+| `JwkThumbprinter` | `thumbprint()`, `thumbprintUri()` | Compute an RFC 7638 thumbprint, plain or as a URI. |
+| `JwksResolver` | `resolve()`, `select()` | Fetch a JWK Set and pick the key matching a header's `kid`/`x5t`/`x5t#S256`. |
+
+```ts
+import type { JwkThumbprinter, JsonWebKey } from '../../../shared/application/http/json-web-token.js'
+
+function fingerprint(thumbprinter: JwkThumbprinter, key: JsonWebKey) {
+    return thumbprinter.thumbprintUri(key)
+}
+```
+
+#### Validating A Token
+
+`JwtValidationResult` is the outcome of checking a token against a
+`JwtValidationPolicy` (`issuers`, `audiences`, `subjects`, `algorithms`,
+`requiredClaims`, `clockToleranceSeconds`, `maxTokenAgeSeconds`, `typ`). It
+has exactly two implementation options, discriminated by `valid`:
+
+| Type | `valid` | Payload |
+| --- | --- | --- |
+| `JwtValidationSuccess` | `true` | `value: DecodedJws<Claims>` |
+| `JwtValidationFailure` | `false` | `code`, `message`, optional `cause` |
+
+`JwtValidationFailure['code']` enumerates the recognized rejection reasons:
+`'malformed'`, `'unsupported_serialization'`, `'unsupported_algorithm'`,
+`'invalid_signature'`, `'decryption_failed'`, `'expired'`, `'not_active'`,
+`'issued_in_future'`, `'issuer_mismatch'`, `'audience_mismatch'`,
+`'subject_mismatch'`, `'missing_claim'`, `'critical_header_unsupported'`, and
+`'policy_rejected'` (plus an open string for adapter-specific codes).
+
+```ts
+import type { JwtValidationResult } from '../../../shared/application/http/json-web-token.js'
+
+function describeResult(result: JwtValidationResult): string {
+    if (result.valid) {
+        return `ok, subject=${result.value.claims.sub}`
+    }
+
+    return `rejected: ${result.code}`
+}
+```
+
+#### Registry Metadata
+
+`JoseAlgorithmRegistryEntry`, `JoseHeaderParameterRegistryEntry`, and
+`JwtClaimRegistryEntry` type the shape of a row describing an algorithm, a
+header parameter, or a claim, for adapters that want to render or validate
+against IANA's own registry data instead of hardcoding the unions above.
+
+> **Hint**
+> This module has no runtime implementation. Choose a JOSE library, then use
+> `JwsSigner`/`JwsVerifier`/`JweEncrypter`/`JweDecrypter`/`JwtDecoder` to
+> annotate its inputs and outputs so the rest of the codebase stays independent
+> from that library's own types.

package/docs/shared/application/http/opengraph.md

@@ -0,0 +1,161 @@
+### Open Graph
+
+`opengraph.ts` declares a type-only implementation of the
+[Open Graph protocol](https://ogp.me/), the Twitter Card meta tags, and
+Facebook's compatibility extensions. It is used when an adapter needs to build
+or read the social-sharing metadata of a page.
+
+This module has no runtime values or implementations, including no HTML
+rendering. Use it to build the data and a separate template or renderer to
+emit the actual `<meta>` tags.
+
+#### Base Shape
+
+Every Open Graph object shares `OpenGraphBase<TType>`: the required `title`,
+`type`, `images` (`OneOrMore<OpenGraphImage>`, first has precedence), and
+`url`, plus the optional `audio`, `description`, `determiner`, `locale`,
+`alternateLocales`, `siteName`, and `videos`. `OpenGraphObjectExtensions`
+adds an optional `extensions` map for CURIE-namespaced custom properties
+(`'product:color'`, etc.), kept as opaque strings.
+
+#### Standard Object Types
+
+`OpenGraphType` selects one of thirteen standard types
+(`OpenGraphStandardType`) or a custom CURIE type
+(`OpenGraphCustomType`, e.g. `'product:item'`). Each standard type has its
+own interface adding the fields that type requires:
+
+| `type` | Interface | Extra fields |
+| --- | --- | --- |
+| `'website'` | `OpenGraphWebsite` | none |
+| `'article'` | `OpenGraphArticle` | `publishedTime`, `modifiedTime`, `expirationTime`, `authors`, `section`, `tags` |
+| `'book'` | `OpenGraphBook` | `authors`, `isbn`, `releaseDate`, `tags` |
+| `'profile'` | `OpenGraphProfile` | `firstName`, `lastName`, `username`, `gender` |
+| `'music.song'` | `OpenGraphMusicSong` | `duration`, `albums`, `musicians` |
+| `'music.album'` | `OpenGraphMusicAlbum` | `songs`, `musicians`, `releaseDate` |
+| `'music.playlist'` | `OpenGraphMusicPlaylist` | `songs`, `creator` |
+| `'music.radio_station'` | `OpenGraphMusicRadioStation` | `creator` |
+| `'video.movie'` | `OpenGraphVideoMovie` | `actors`, `directors`, `writers`, `duration`, `releaseDate`, `tags` (`OpenGraphVideoMetadata`) |
+| `'video.episode'` | `OpenGraphVideoEpisode` | `OpenGraphVideoMetadata` + `series` |
+| `'video.tv_show'` | `OpenGraphVideoTvShow` | `OpenGraphVideoMetadata` |
+| `'video.other'` | `OpenGraphVideoOther` | `OpenGraphVideoMetadata` |
+| `'payment.link'` | `OpenGraphPaymentLink` | `paymentDescription`, `currency`, `amount`, `expiresAt`, `paymentStatus`, `paymentId`, `successUrl` (marked beta by the protocol) |
+| CURIE type | `OpenGraphCustomObject` | none beyond the base shape |
+
+`OpenGraphMetadata` is the union of all fourteen. Building one selects the
+type through the discriminant and, from there, TypeScript narrows to that
+type's own extra fields.
+
+```ts title="users/adapters/user-profile-metadata.ts"
+import { OpenGraphProfile } from '../../shared/application/http/opengraph.js'
+
+export function buildProfileMetadata(username: string): OpenGraphProfile {
+    return {
+        type: 'profile',
+        title: username,
+        url: `https://example.com/users/${username}`,
+        images: [{ url: `https://example.com/users/${username}/avatar.png` }],
+        username,
+    }
+}
+```
+
+```ts title="users/adapters/article-metadata.ts"
+import { OpenGraphArticle } from '../../shared/application/http/opengraph.js'
+
+export function buildArticleMetadata(slug: string): OpenGraphArticle {
+    return {
+        type: 'article',
+        title: 'How context ports work',
+        url: `https://example.com/blog/${slug}`,
+        images: [{ url: `https://example.com/blog/${slug}/cover.png` }],
+        publishedTime: new Date().toISOString(),
+        tags: ['architecture', 'typescript'],
+    }
+}
+```
+
+`OpenGraphPaymentStatus` (`'PENDING' | 'PAID' | 'FAILED' | 'EXPIRED'`) types
+`OpenGraphPaymentLink['paymentStatus']`.
+
+#### Twitter Cards
+
+`TwitterCardType` selects one of four card layouts. `TwitterCardBase<TCard>`
+carries the members every card shares (`site`, `siteId`, `creator`,
+`creatorId`, `title`, `description`); each concrete card adds the fields that
+layout needs:
+
+| `card` | Interface | Extra/required fields |
+| --- | --- | --- |
+| `'summary'` | `TwitterSummaryCard` | optional `image` |
+| `'summary_large_image'` | `TwitterSummaryLargeImageCard` | optional `image` |
+| `'player'` | `TwitterPlayerCard` | required `image`, `player`, `playerWidth`, `playerHeight`; optional `playerStream`, `playerStreamContentType` |
+| `'app'` | `TwitterAppCard` | optional `country`, `iphone`, `ipad`, `googlePlay` (each `TwitterAppPlatform`) |
+
+`TwitterCardMetadata` is the union of all four.
+
+```ts
+import type { TwitterPlayerCard } from '../../../shared/application/http/opengraph.js'
+
+const playerCard: TwitterPlayerCard = {
+    card: 'player',
+    image: { url: 'https://example.com/videos/1/thumb.png' },
+    player: 'https://example.com/videos/1/embed',
+    playerWidth: 640,
+    playerHeight: 360,
+}
+```
+
+#### Raw Meta Tag Representation
+
+`OpenGraphMetaTag`/`TwitterMetaTag` are the flat `property`/`content` and
+`name`/`content` tag forms closer to the actual `<meta>` markup, for a
+renderer that emits tags directly instead of consuming the structured
+objects above.
+
+| Tag family | Type | Attribute pair |
+| --- | --- | --- |
+| Open Graph (standard) | `OpenGraphStandardMetaTag` | `property`/`content`, e.g. `'og:title'` |
+| Open Graph (custom) | `OpenGraphCustomMetaTag` | any `` `${string}:${string}` `` property |
+| Twitter | `TwitterMetaTag` | `name`/`content`, e.g. `'twitter:card'` |
+| Facebook | `FacebookMetaTag` | `PropertyMetaTag<'fb:app_id'>` |
+| Standard HTML | `StandardHtmlMetaTag` | `'description'` \| `'theme-color'` |
+
+`SocialMetaTag` is the union of all five families. `CanonicalLinkTag` types
+the `<link rel="canonical">` element separately, since it is not a `<meta>`
+tag.
+
+#### Aggregate Document
+
+Two document shapes cover the two stages of building a page's social
+metadata:
+
+| Type | Shape | Use |
+| --- | --- | --- |
+| `SocialMetadataDocument` | `head?`, `openGraph` (required), `twitter?`, `facebook?` | Structured data a service builds before rendering |
+| `RawSocialMetadataDocument` | `title?`, `meta: SocialMetaTag[]`, `links?: CanonicalLinkTag[]` | The rendered, tag-list form a template consumes |
+
+```ts title="users/adapters/social-metadata-document.ts"
+import {
+    SocialMetadataDocument,
+    OpenGraphProfile,
+} from '../../shared/application/http/opengraph.js'
+
+export function buildSocialMetadata(profile: OpenGraphProfile): SocialMetadataDocument {
+    return {
+        head: { title: profile.title, description: profile.description },
+        openGraph: profile,
+        twitter: { card: 'summary', title: profile.title },
+    }
+}
+```
+
+Converting a `SocialMetadataDocument` into a `RawSocialMetadataDocument` is
+the responsibility of a renderer, which flattens each structured field into
+its corresponding `SocialMetaTag` entries; that conversion is not implemented
+by this module.
+
+> **Hint**
+> This module has no runtime implementation, including no HTML rendering. Use
+> `OpenGraphMetadata` to build the data and a separate template or renderer to
+> emit the `<meta>` tags described by `OpenGraphMetaTag`/`TwitterMetaTag`.

package/docs/shared/application/loggers.md

@@ -28,8 +28,8 @@ any adapter to use a particular logger implementation.
 `Logger` is responsible for receiving log data from the application layer.
 
 ```ts title="shared/application/loggers.ts"
-import { type TimeZone } from '../../types/iana.js'
-import { type Locale } from '../../types/cldr.js'
+import { type TimeZone } from '../../types/timezones.js'
+import { type Locale } from '../../types/locales.js'
 
 export abstract class Logger {
     [property: string]: unknown
@@ -74,8 +74,9 @@ request, while the adapter decides how those actions are persisted or displayed.
 `name` and `level` identify the logger instance and its minimum severity, so an
 adapter can decide which logs to emit or route. `datetimeLocales` and
 `datetimeFormatOptions` control how `getCurrentDatetime()` formats the current
-moment, using the `Locale` type from `types/cldr.d.ts` and the `TimeZone` type
-from `types/iana.d.ts`. Adapters can use `getCurrentDatetime()` to timestamp
+moment, using the `Locale` type from `types/locales.d.ts` (see
+`types/locales.md`) and the `TimeZone` type from `types/timezones.d.ts` (see
+`types/timezones.md`). Adapters can use `getCurrentDatetime()` to timestamp
 log entries consistently, regardless of the runtime environment's own locale
 or timezone.