@sdxc/well-known 2026.10.24 → 2026.10.26

package/dist/client-id-metadata-document.js

@@ -0,0 +1,294 @@
+import { success } from "@sdxc/result";
+import { jwks } from "./jwks.js";
+import { isObject, pointer } from "./lib/json.js";
+import { defaults, readMetadata, writeMetadata } from "./lib/metadata.js";
+export const NAME = "client-id-metadata-document";
+export const MEDIA_TYPE = "application/json";
+/**
+ * The client authentication methods a document may declare (§4.1): `none` and the
+ * methods proven with a key pair, since a published document can establish no shared
+ * secret.
+ */
+export const TOKEN_ENDPOINT_AUTH_METHODS = [
+    "none",
+    "private_key_jwt",
+    "tls_client_auth",
+    "self_signed_tls_client_auth",
+];
+/** The methods whose key the authorization server discovers through `jwks` or `jwks_uri`. */
+const KEYED_METHODS = ["private_key_jwt", "self_signed_tls_client_auth"];
+/** The registered methods built on a shared secret, refused by name (§4.1). */
+const SECRET_METHODS = [
+    "client_secret_post",
+    "client_secret_basic",
+    "client_secret_jwt",
+];
+/** Members that carry a shared secret, which a document must never hold (§4.1). */
+const SECRET_MEMBERS = ["client_secret", "client_secret_expires_at"];
+/** Grant types that send the user back through a registered redirect URI (§4.2). */
+const REDIRECT_GRANTS = ["authorization_code", "implicit"];
+/** Schemes a redirect URI may never use, since following one runs or embeds content. */
+const UNSAFE_REDIRECT_SCHEMES = ["javascript:", "data:", "vbscript:", "file:"];
+/** The schemes a URL shown to the user or linked from the consent screen may use (§8.6). */
+const WEB_SCHEMES = ["https:", "http:"];
+/** Every RFC 7591 §2 member this document types, by camelCase field. */
+const FIELDS = {
+    clientId: { wire: "client_id", kind: "text", required: true },
+    redirectUris: { wire: "redirect_uris", kind: "strings" },
+    tokenEndpointAuthMethod: { wire: "token_endpoint_auth_method", kind: "text" },
+    grantTypes: { wire: "grant_types", kind: "strings", default: ["authorization_code"] },
+    responseTypes: { wire: "response_types", kind: "strings", default: ["code"] },
+    clientName: { wire: "client_name", kind: "localized" },
+    clientUri: { wire: "client_uri", kind: "url" },
+    logoUri: { wire: "logo_uri", kind: "url" },
+    scope: { wire: "scope", kind: "tokens" },
+    contacts: { wire: "contacts", kind: "strings" },
+    tosUri: { wire: "tos_uri", kind: "url" },
+    policyUri: { wire: "policy_uri", kind: "url" },
+    jwksUri: { wire: "jwks_uri", kind: "url" },
+    jwks: { wire: "jwks", kind: "object" },
+    softwareId: { wire: "software_id", kind: "text" },
+    softwareVersion: { wire: "software_version", kind: "text" },
+    softwareStatement: { wire: "software_statement", kind: "text" },
+};
+/**
+ * Whether a string is a valid Client Identifier URL (§3): `https`, a path, and no
+ * userinfo, dot segments or fragment. It reads the raw string, so a dot segment the URL
+ * parser would resolve away still fails; a query is allowed, though discouraged.
+ *
+ * @param value - A `client_id` as presented.
+ * @example
+ * isClientIdentifierUrl("https://app.example.com/client.json"); // true
+ */
+export function isClientIdentifierUrl(value) {
+    if (!/^https:\/\//i.test(value) || !URL.canParse(value))
+        return false;
+    if (value.includes("#"))
+        return false;
+    let rest = value.slice("https://".length);
+    let end = rest.search(/[/?]/);
+    if (end === -1 || rest[end] !== "/")
+        return false;
+    if (rest.slice(0, end).includes("@"))
+        return false;
+    let path = rest.slice(end).split("?")[0] ?? "";
+    return path.split("/").every((segment) => !/^(\.|%2e){1,2}$/i.test(segment));
+}
+/**
+ * Whether a redirect URI can be registered: an absolute URL without a fragment (RFC 6749
+ * §3.1.2) whose scheme leads somewhere a browser navigates to safely.
+ *
+ * @param value - One entry of `redirect_uris`.
+ */
+function isRedirectUri(value) {
+    if (!URL.canParse(value) || value.includes("#"))
+        return false;
+    return !UNSAFE_REDIRECT_SCHEMES.includes(new URL(value).protocol);
+}
+/**
+ * Collects every §4.1 key material problem in `jwks`: no `keys` array, or a key carrying
+ * a private or symmetric member.
+ *
+ * @param set - The decoded `jwks` member.
+ * @param issues - Where problems are collected.
+ */
+function checkKeys(set, issues) {
+    let keys = set.keys;
+    if (!Array.isArray(keys)) {
+        issues.push({ at: "/jwks/keys", message: '"jwks" has no "keys" array.' });
+        return;
+    }
+    for (let [index, key] of keys.entries()) {
+        if (!isObject(key)) {
+            issues.push({
+                at: pointer("jwks", "keys", index),
+                message: `Key ${index} is not an object.`,
+            });
+            continue;
+        }
+        for (let member of ["d", "p", "q", "dp", "dq", "qi", "oth", "k"]) {
+            if (member in key)
+                issues.push({
+                    at: pointer("jwks", "keys", index, member),
+                    message: `Key ${index} carries the private member "${member}".`,
+                });
+        }
+    }
+}
+/**
+ * Collects the §4.1 authentication problems: a secret member, a method outside
+ * {@link TOKEN_ENDPOINT_AUTH_METHODS}, both or neither key source for a keyed method, a
+ * non-`https` `jwks_uri` and private key material.
+ *
+ * @param fields - The read fields.
+ * @param issues - Where problems are collected.
+ * @param body - The decoded document.
+ */
+function checkAuthentication(fields, issues, body) {
+    for (let member of SECRET_MEMBERS) {
+        if (member in body)
+            issues.push({
+                at: pointer(member),
+                message: `"${member}" is a shared secret, which a Client ID Metadata Document cannot carry.`,
+            });
+    }
+    let method = fields.tokenEndpointAuthMethod ?? "none";
+    if (SECRET_METHODS.includes(method)) {
+        issues.push({
+            at: "/token_endpoint_auth_method",
+            message: `"${method}" authenticates with a shared secret, which a Client ID Metadata Document cannot establish.`,
+        });
+    }
+    else if (!TOKEN_ENDPOINT_AUTH_METHODS.includes(method)) {
+        issues.push({
+            at: "/token_endpoint_auth_method",
+            message: `"${method}" is not one of ${TOKEN_ENDPOINT_AUTH_METHODS.join(", ")}.`,
+        });
+    }
+    let jwksUri = fields.jwksUri;
+    let set = fields.jwks;
+    if (jwksUri !== null && set !== null)
+        issues.push({ at: "", message: 'The document sets both "jwks" and "jwks_uri".' });
+    if (KEYED_METHODS.includes(method) && jwksUri === null && set === null)
+        issues.push({
+            at: "/token_endpoint_auth_method",
+            message: `"${method}" needs the client's public key in "jwks" or "jwks_uri".`,
+        });
+    if (jwksUri !== null && jwksUri.protocol !== "https:")
+        issues.push({ at: "/jwks_uri", message: '"jwks_uri" is not an https URL.' });
+    if (set !== null)
+        checkKeys(set, issues);
+}
+/**
+ * Collects the §4.2 and §8.6 URL problems: a redirect URI that cannot be registered, no
+ * redirect URI for a redirect-based grant, and a display URL outside `http`/`https`.
+ *
+ * @param fields - The read fields.
+ * @param issues - Where problems are collected.
+ */
+function checkUrls(fields, issues) {
+    let redirectUris = fields.redirectUris;
+    for (let [index, uri] of redirectUris.entries()) {
+        if (!isRedirectUri(uri))
+            issues.push({
+                at: pointer("redirect_uris", index),
+                message: `"${uri}" is not an absolute redirect URI without a fragment.`,
+            });
+    }
+    let grantTypes = fields.grantTypes;
+    if (redirectUris.length === 0 && grantTypes.some((grant) => REDIRECT_GRANTS.includes(grant)))
+        issues.push({
+            at: "/redirect_uris",
+            message: `"redirect_uris" is empty, and grant types ${grantTypes.join(", ")} need one.`,
+        });
+    for (let name of ["clientUri", "logoUri", "tosUri", "policyUri"]) {
+        let url = fields[name];
+        if (url !== null && !WEB_SCHEMES.includes(url.protocol))
+            issues.push({
+                at: pointer(FIELDS[name].wire),
+                message: `"${FIELDS[name].wire}" is not an http or https URL.`,
+            });
+    }
+}
+/**
+ * Builds the read's draft check: the `client_id` shape (§3), its match with the fetched
+ * URL when one is given (§4), and the credential and URL rules.
+ *
+ * @param expected - The URL the document was fetched from.
+ */
+function documentCheck(expected) {
+    return (fields, issues, body) => {
+        let clientId = String(fields.clientId);
+        if (!isClientIdentifierUrl(clientId))
+            issues.push({
+                at: "/client_id",
+                message: `"${clientId}" is not an https URL with a path and no userinfo, dot segments or fragment.`,
+            });
+        else if (expected !== undefined && clientId !== expected)
+            issues.push({
+                at: "/client_id",
+                message: `The document names client_id "${clientId}", not "${expected}".`,
+            });
+        checkAuthentication(fields, issues, body);
+        checkUrls(fields, issues);
+    };
+}
+/**
+ * Reads a document through the field table and the draft's rules.
+ *
+ * @param text - The served JSON.
+ * @param expected - The URL it was fetched from, when the match is checked.
+ * @param extensions - The extension schema.
+ * @template Extensions - The extension members the schema produces.
+ */
+function read(text, expected, extensions) {
+    let result = readMetadata(text, {
+        format: NAME,
+        table: FIELDS,
+        extensions,
+        check: documentCheck(expected),
+    });
+    if (result.status === "failure")
+        return result;
+    return success({
+        ...result.data,
+        tokenEndpointAuthMethod: result.data.tokenEndpointAuthMethod ?? "none",
+    });
+}
+/**
+ * Reads a fetched document. It fails on a `client_id` other than `options.clientId`, a
+ * `client_secret*` member, a secret-based or unknown `token_endpoint_auth_method`, a
+ * keyed method without exactly one key source, private key material, or a redirect URI
+ * the client could not register; every RFC 7591 member outside the list lands in `extensions`.
+ *
+ * @param text - The served JSON.
+ * @param options - The fetched URL and an extension schema.
+ * @template Extensions - The extension members the schema produces.
+ * @example
+ * let client = parse(await response.text(), { clientId: url });
+ */
+export function parse(text, options) {
+    return read(text, options.clientId, options.extensions);
+}
+/**
+ * Writes the document as its registered member names, leaving out `null` members, empty
+ * optional lists and default grant and response types. `token_endpoint_auth_method` is
+ * always written, since RFC 7591 reads an absent one as `client_secret_basic`, and
+ * `jwks` carries each key's public half only.
+ *
+ * @param document - The metadata to publish.
+ */
+export function stringify(document) {
+    let set = document.jwks === null ? null : JSON.parse(jwks.stringify(document.jwks));
+    return writeMetadata({ ...document, jwks: set }, FIELDS);
+}
+/**
+ * Builds a document from the members a client sets: `none` authentication, the RFC 7591
+ * default grant and response types, empty lists, `null` single values and no extensions.
+ *
+ * @param document - The members the client publishes.
+ * @template Extensions - Members outside the typed list the client also publishes.
+ * @example
+ * define({ clientId: "https://app.example.com/client.json", redirectUris: ["https://app.example.com/callback"] });
+ */
+export function define(document) {
+    return {
+        ...defaults(FIELDS),
+        tokenEndpointAuthMethod: "none",
+        extensions: {},
+        ...document,
+    };
+}
+/**
+ * The document as a servable format, for `respond` from `./response` at the route behind
+ * the client's own URL. Its `parse` applies every rule but the URL match, which a
+ * fetching authorization server checks by calling `parse` with `clientId`.
+ */
+export const clientIdMetadataDocument = {
+    name: NAME,
+    mediaType: MEDIA_TYPE,
+    placement: "insert",
+    cors: false,
+    stringify,
+    parse: (text) => read(text, undefined, undefined),
+};

package/dist/format.d.ts

@@ -1,6 +1,6 @@
 /**
  * The description every well-known document shares: its registered name, media type,
- * URL placement and CORS rule beside its reader and writer, which is what lets one
+ * URL placement, CORS rule and fixed headers beside its reader and writer, which is what lets one
  * response helper and one middleware serve any of them.
  *
  * @author [Sergio Xalambrí](https://sergiodxa.com)
@@ -27,6 +27,8 @@ export interface WellKnownFormat<Document> {
     readonly placement: WellKnownPlacement;
     /** Whether every answer carries `Access-Control-Allow-Origin: *`. */
     readonly cors: boolean;
+    /** Headers every answer carries, `HEAD` included, such as the `Link` an API catalog requires. */
+    readonly headers?: Readonly<Record<string, string>>;
     /** The document as the text served under the name. */
     stringify(document: Document): string;
     /** Reads served text back, reporting every place it breaks the specification. */

package/dist/http-message-signatures-directory.d.ts

@@ -0,0 +1,54 @@
+/**
+ * The HTTP Message Signatures Directory of Web Bot Auth: the JWK Set an automated client
+ * publishes at `/.well-known/http-message-signatures-directory` so any origin can verify
+ * the requests it signs, each key labelled with its RFC 7638 thumbprint as `kid`.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import type { Result } from "@sdxc/result";
+import type { WellKnownFormat } from "./format.js";
+import type { Jwk } from "./jwks.js";
+import { WellKnownParseError } from "./parse-error.js";
+export declare const NAME = "http-message-signatures-directory";
+export declare const MEDIA_TYPE = "application/http-message-signatures-directory+json";
+/** A directory key: a public JWK, optionally bounded by `nbf` and `exp` in epoch seconds. */
+export interface DirectoryKey extends Jwk {
+    nbf?: number;
+    exp?: number;
+}
+export interface SignaturesDirectory {
+    keys: DirectoryKey[];
+}
+export interface ParsedSignaturesDirectory extends SignaturesDirectory {
+    /**
+     * Entries dropped: unusable as a JWK, symmetric, carrying private members, declaring an
+     * `alg` outside the HTTP Signature Algorithms registry, or with a non-numeric `nbf`/`exp`.
+     */
+    skipped: number;
+}
+/**
+ * Reads a directory. A missing or non-array `keys` fails; every entry a verifier could not
+ * use is dropped and counted in `skipped`, so one bad key never hides the others.
+ *
+ * @param text - The served JSON.
+ * @example let directory = parse(await response.text());
+ */
+export declare function parse(text: string): Result<ParsedSignaturesDirectory, WellKnownParseError>;
+/**
+ * Builds a directory from keys, public or private: each entry keeps its public members,
+ * `kid`, `alg`, `nbf` and `exp`, and gets `use: "sig"`. Verifiers match a signature's
+ * `keyid` against `kid`, so set it to the key's RFC 7638 thumbprint (`JWK.thumbprint`).
+ *
+ * @param keys - The signing keys; a private JWK publishes only its public half.
+ * @returns The directory, or an issue at every symmetric key, every key without `kid`, and
+ *   every `alg` outside the HTTP Signature Algorithms registry, such as JOSE's `EdDSA`.
+ * @example build([{ ...publicJwk, kid: await thumbprintOf(publicJwk) }])
+ */
+export declare function build(keys: DirectoryKey[]): Result<SignaturesDirectory, WellKnownParseError>;
+/**
+ * A directory as a servable format, answered with the registered media type and
+ * `Access-Control-Allow-Origin: *` so a browser-based verifier can read it. Serving keeps
+ * the public half of every asymmetric key; pass what `build` answers so each carries its `kid`.
+ */
+export declare const httpMessageSignaturesDirectory: WellKnownFormat<SignaturesDirectory>;

package/dist/http-message-signatures-directory.js

@@ -0,0 +1,115 @@
+import { failure, isFailure, success } from "@sdxc/result";
+import { parse as parseJwks } from "./jwks.js";
+import { pointer } from "./lib/json.js";
+import { WellKnownParseError } from "./parse-error.js";
+export const NAME = "http-message-signatures-directory";
+export const MEDIA_TYPE = "application/http-message-signatures-directory+json";
+/** The asymmetric algorithms the HTTP Signature Algorithms registry (RFC 9421 §6.2) lists. */
+const SIGNATURE_ALGORITHMS = new Set([
+    "rsa-pss-sha512",
+    "rsa-v1_5-sha256",
+    "ecdsa-p256-sha256",
+    "ecdsa-p384-sha384",
+    "ed25519",
+]);
+/** Members that carry private or symmetric key material (RFC 7518 §6). */
+const PRIVATE_MEMBERS = ["d", "p", "q", "dp", "dq", "qi", "oth", "k"];
+/**
+ * Whether a usable JWK may stand in a directory: asymmetric and public, since the draft
+ * forbids shared secrets, with a registered `alg` when it names one.
+ *
+ * @param key - An entry the JWK Set reader kept.
+ */
+function isDirectoryKey(key) {
+    if (key.kty === "oct")
+        return false;
+    if (PRIVATE_MEMBERS.some((member) => member in key))
+        return false;
+    if (key.alg !== undefined && !SIGNATURE_ALGORITHMS.has(key.alg))
+        return false;
+    let { nbf, exp } = key;
+    return [nbf, exp].every((bound) => bound === undefined || typeof bound === "number");
+}
+/**
+ * A key without its private members, `key_ops` and `ext`, which a published key never needs, or
+ * `null` for a symmetric key, which has no public half.
+ *
+ * @param key - A key, public or private.
+ */
+function publicHalf(key) {
+    if (key.kty === "oct")
+        return null;
+    let half = { ...key };
+    for (let member of PRIVATE_MEMBERS)
+        delete half[member];
+    delete half.key_ops;
+    delete half.ext;
+    return half;
+}
+/**
+ * Reads a directory. A missing or non-array `keys` fails; every entry a verifier could not
+ * use is dropped and counted in `skipped`, so one bad key never hides the others.
+ *
+ * @param text - The served JSON.
+ * @example let directory = parse(await response.text());
+ */
+export function parse(text) {
+    let set = parseJwks(text);
+    if (isFailure(set)) {
+        return failure(new WellKnownParseError(NAME, set.error.issues));
+    }
+    let keys = set.data.keys.filter(isDirectoryKey);
+    let skipped = set.data.skipped + set.data.keys.length - keys.length;
+    return success({ keys, skipped });
+}
+/**
+ * Builds a directory from keys, public or private: each entry keeps its public members,
+ * `kid`, `alg`, `nbf` and `exp`, and gets `use: "sig"`. Verifiers match a signature's
+ * `keyid` against `kid`, so set it to the key's RFC 7638 thumbprint (`JWK.thumbprint`).
+ *
+ * @param keys - The signing keys; a private JWK publishes only its public half.
+ * @returns The directory, or an issue at every symmetric key, every key without `kid`, and
+ *   every `alg` outside the HTTP Signature Algorithms registry, such as JOSE's `EdDSA`.
+ * @example build([{ ...publicJwk, kid: await thumbprintOf(publicJwk) }])
+ */
+export function build(keys) {
+    let issues = [];
+    let published = [];
+    for (let [index, key] of keys.entries()) {
+        let half = publicHalf(key);
+        if (half === null) {
+            issues.push({ at: pointer("keys", index), message: `Key ${index} is symmetric.` });
+        }
+        else if (half.kid === undefined) {
+            issues.push({ at: pointer("keys", index, "kid"), message: `Key ${index} has no kid.` });
+        }
+        else if (half.alg !== undefined && !SIGNATURE_ALGORITHMS.has(half.alg)) {
+            issues.push({
+                at: pointer("keys", index, "alg"),
+                message: `Key ${index}'s alg "${half.alg}" is no HTTP signature algorithm.`,
+            });
+        }
+        else {
+            published.push({ ...half, use: "sig" });
+        }
+    }
+    if (issues.length > 0)
+        return failure(new WellKnownParseError(NAME, issues));
+    return success({ keys: published });
+}
+/**
+ * A directory as a servable format, answered with the registered media type and
+ * `Access-Control-Allow-Origin: *` so a browser-based verifier can read it. Serving keeps
+ * the public half of every asymmetric key; pass what `build` answers so each carries its `kid`.
+ */
+export const httpMessageSignaturesDirectory = {
+    name: NAME,
+    mediaType: MEDIA_TYPE,
+    placement: "append",
+    cors: true,
+    stringify(document) {
+        let keys = document.keys.map(publicHalf).filter((key) => key !== null);
+        return JSON.stringify({ keys });
+    },
+    parse,
+};

package/dist/lib/metadata.d.ts

@@ -1,7 +1,7 @@
 /**
  * The field-mapping engine behind the OAuth metadata documents (RFC 8414, OpenID
- * Connect Discovery, RFC 9728): one table maps each camelCase field to its registered
- * member name and kind, and drives reading, writing and defaults from that one place.
+ * Connect Discovery, RFC 9728, RFC 7591 client metadata): one table maps each camelCase
+ * field to its member name and kind, and drives reading, writing and defaults from it.
  *
  * @author [Sergio Xalambrí](https://sergiodxa.com)
  * @copyright Sergio Xalambrí 2026
@@ -9,12 +9,14 @@
 import type { Result } from "@sdxc/result";
 import type { StandardSchemaV1 } from "@standard-schema/spec";
 import { WellKnownParseError } from "../parse-error.js";
+import type { JsonObject } from "./json.js";
 /**
  * How a member's JSON value maps to its field: `text` is a string, `url` one absolute
- * URL, `urls` and `strings` lists, `boolean` a flag, and `localized` a human-readable
- * string with `#`-tagged language variants (RFC 9728 §2.1).
+ * URL, `urls` and `strings` lists, `tokens` a space-delimited string read as a list (RFC
+ * 7591 `scope`), `object` a JSON object kept as decoded, `boolean` a flag, and `localized`
+ * a human-readable string with `#`-tagged language variants (RFC 9728 §2.1).
  */
-export type FieldKind = "text" | "url" | "urls" | "strings" | "boolean" | "localized";
+export type FieldKind = "text" | "url" | "urls" | "strings" | "tokens" | "object" | "boolean" | "localized";
 /** One row of the mapping table. */
 export interface Field {
     /** The member name the specification registers. */
@@ -22,8 +24,8 @@ export interface Field {
     kind: FieldKind;
     /** A missing member fails the parse instead of taking the default. */
     required?: boolean;
-    /** The value an absent boolean member means, which `stringify` leaves unwritten. */
-    default?: boolean;
+    /** The value an absent boolean or `strings` member means, which `stringify` leaves unwritten. */
+    default?: boolean | readonly string[];
     /** The only values a `strings` member may list. */
     values?: readonly string[];
 }
@@ -40,8 +42,11 @@ export interface ReadOptions<Extensions extends object> {
     format: string;
     table: FieldTable;
     extensions?: StandardSchemaV1<unknown, Extensions>;
-    /** Checks the read fields against what the caller expected, adding issues on a mismatch. */
-    check?: (fields: Record<string, unknown>, issues: WellKnownParseError.Issue[]) => void;
+    /**
+     * Checks the read fields against what the caller expected, adding issues on a mismatch;
+     * `body` is the decoded document, for a rule about a member outside the table.
+     */
+    check?: (fields: Record<string, unknown>, issues: WellKnownParseError.Issue[], body: JsonObject) => void;
 }
 /**
  * Reads a metadata document through its table. Members outside the table become the

package/dist/lib/metadata.js

@@ -1,6 +1,6 @@
 import { failure, success } from "@sdxc/result";
 import { WellKnownParseError } from "../parse-error.js";
-import { pointer, readExtensions, readJsonObject } from "./json.js";
+import { isObject, pointer, readExtensions, readJsonObject } from "./json.js";
 /**
  * The value an absent member takes: `null` for single values, an empty list for
  * lists, and the specification's default for flags.
@@ -8,12 +8,25 @@ import { pointer, readExtensions, readJsonObject } from "./json.js";
  * @param field - The row to default.
  */
 function defaultOf(field) {
-    if (field.kind === "urls" || field.kind === "strings")
-        return [];
+    if (field.kind === "urls" || field.kind === "strings" || field.kind === "tokens")
+        return Array.isArray(field.default) ? [...field.default] : [];
     if (field.kind === "boolean")
         return field.default ?? false;
     return null;
 }
+/**
+ * Whether a list holds exactly a field's default list, in order, so the writer leaves a
+ * member out only when reading it back gives the same value.
+ *
+ * @param value - The field's list.
+ * @param field - The row it belongs to.
+ */
+function isDefaultList(value, field) {
+    if (!Array.isArray(field.default))
+        return false;
+    let list = field.default;
+    return value.length === list.length && value.every((entry, index) => entry === list[index]);
+}
 /**
  * Every field of a table at its default, for `define` to lay the app's values over.
  *
@@ -81,6 +94,18 @@ function readField(body, field, issues) {
             issues.push({ at, message: `"${field.wire}" is not an absolute URL.` });
             return null;
         }
+        case "tokens": {
+            if (typeof value === "string")
+                return value.split(" ").filter(Boolean);
+            issues.push({ at, message: `"${field.wire}" is not a space-delimited string.` });
+            return [];
+        }
+        case "object": {
+            if (isObject(value))
+                return value;
+            issues.push({ at, message: `"${field.wire}" is not a JSON object.` });
+            return null;
+        }
         case "boolean": {
             if (typeof value === "boolean")
                 return value;
@@ -184,7 +209,7 @@ export function readMetadata(text, options) {
     for (let [name, field] of Object.entries(options.table))
         fields[name] = readField(body, field, issues);
     if (issues.length === 0)
-        options.check?.(fields, issues);
+        options.check?.(fields, issues, body);
     let members = {};
     for (let [member, value] of Object.entries(body)) {
         if (!isStandardMember(options.table, member))
@@ -219,8 +244,14 @@ export function writeMetadata(document, table) {
         if (value === null || value === undefined)
             continue;
         if (Array.isArray(value)) {
-            if (value.length === 0 && !field.required)
+            if (isDefaultList(value, field))
+                continue;
+            if (value.length === 0 && !field.required && !Array.isArray(field.default))
+                continue;
+            if (field.kind === "tokens") {
+                output[field.wire] = value.join(" ");
                 continue;
+            }
             output[field.wire] = value.map((entry) => (entry instanceof URL ? entry.href : entry));
             continue;
         }