@openvtc/trust-tasks 0.27.7 → 0.27.9

package/src/_runtime/extends.ts

@@ -29,14 +29,21 @@
 import { EXTENDS_BY_TYPE_URI } from "../_extends.js";
 import { canonicalJson } from "./canonical.js";
 import type { RejectReason, SpecPolicy, TrustTaskDocument } from "./document.js";
+import {
+  formatTypeUri,
+  sameSpecification,
+  tryParseTypeUri,
+  typeUriWithVersion,
+  type TypeUri,
+} from "./type-uri.js";
 
-const PREFIX = "https://trusttasks.org/spec/";
 const VERSION_RE = /^(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)$/;
 
 /**
  * Where to look up the version a Type URI declares it extends. Either a map
  * from bare request Type URI to version (the shape of the generated
- * `EXTENDS_BY_TYPE_URI`), or a function. Defaults to the generated index; pass
+ * `EXTENDS_BY_TYPE_URI`), or a function. Defaults to the generated index plus
+ * the tables an application registered with {@link declareExtends}; pass
  * your own to route on knowledge this library release does not carry, or in a
  * test.
  */
@@ -44,27 +51,54 @@ export type ExtendsLookup =
   | Readonly<Record<string, string>>
   | ((bareTypeUri: string) => string | null | undefined);
 
-interface ParsedTypeUri {
-  slug: string;
-  version: string;
-  major: number;
-  minor: number;
-  /** `""`, or the fragment including its `#`. */
-  fragment: string;
+/** `M.N` of a parsed Type URI. */
+const versionOf = (u: TypeUri): string => `${u.major}.${u.minor}`;
+
+/**
+ * The key an {@link ExtendsLookup} is consulted with: the bare (fragment-free)
+ * request Type URI of `u` at `version`, under `u`'s own authority and form.
+ * Building it from `u` rather than from the slug is what keeps a chain inside
+ * one authority: a third-party `x/0.3` is never looked up as the registry's
+ * `x/0.3`.
+ */
+function bareKey(u: TypeUri): string {
+  return formatTypeUri({ ...u, variant: null });
 }
 
-function parseTypeUri(typeUri: string): ParsedTypeUri | null {
-  if (typeof typeUri !== "string" || !typeUri.startsWith(PREFIX)) return null;
-  const hash = typeUri.indexOf("#");
-  const bare = hash < 0 ? typeUri : typeUri.slice(0, hash);
-  const fragment = hash < 0 ? "" : typeUri.slice(hash);
-  const rest = bare.slice(PREFIX.length);
-  const cut = rest.lastIndexOf("/");
-  if (cut <= 0) return null;
-  const version = rest.slice(cut + 1);
-  const m = VERSION_RE.exec(version);
-  if (!m) return null;
-  return { slug: rest.slice(0, cut), version, major: Number(m[1]), minor: Number(m[2]), fragment };
+/**
+ * Tables an application registered with {@link declareExtends}, in the order
+ * they were declared.
+ */
+const APPLICATION_EXTENDS: Readonly<Record<string, string>>[] = [];
+
+/**
+ * Teach the default lookup — {@link extendsOf}, {@link extendsChain} and
+ * {@link readForSpec} when no `index` is passed — the `extends` declarations
+ * of specification versions this package's generated table does not carry:
+ * those an application generated itself from registry bundles with
+ * `trust-tasks-gen-ts` (`@openvtc/trust-tasks-gen`).
+ *
+ * Each key is a bare request Type URI and each value the `"MAJOR.MINOR"` it
+ * extends — the shape of the generated `EXTENDS_BY_TYPE_URI`. The `index.ts`
+ * the generator writes exports a `declareExtends()` that calls this with its
+ * table, so an application calls that once at start-up.
+ *
+ * Process-wide and additive. Declaring the same table twice is harmless, and
+ * where this package's generated table already answers for a Type URI that
+ * answer stands. A declaration is still only followed when it names a strictly
+ * earlier MINOR of the same MAJOR (SPEC §5.2).
+ */
+export function declareExtends(declarations: Readonly<Record<string, string>>): void {
+  if (!APPLICATION_EXTENDS.includes(declarations)) APPLICATION_EXTENDS.push(declarations);
+}
+
+const hasOwn = (o: object, k: string): boolean => Object.prototype.hasOwnProperty.call(o, k);
+
+/** The default {@link ExtendsLookup}: the generated table, then {@link declareExtends}'s. */
+function defaultLookup(bare: string): string | undefined {
+  if (hasOwn(EXTENDS_BY_TYPE_URI, bare)) return EXTENDS_BY_TYPE_URI[bare];
+  for (const table of APPLICATION_EXTENDS) if (hasOwn(table, bare)) return table[bare];
+  return undefined;
 }
 
 function lookup(index: ExtendsLookup, bare: string): string | null {
@@ -77,32 +111,40 @@ function lookup(index: ExtendsLookup, bare: string): string | null {
  * `#request` / `#response` fragment is ignored — the declaration is the
  * specification's, covering both variants.
  */
-export function extendsOf(typeUri: string, index: ExtendsLookup = EXTENDS_BY_TYPE_URI): string | null {
-  const p = parseTypeUri(typeUri);
+export function extendsOf(typeUri: string, index: ExtendsLookup = defaultLookup): string | null {
+  const p = tryParseTypeUri(typeUri);
   if (p === null) return null;
-  return lookup(index, `${PREFIX}${p.slug}/${p.version}`);
+  return lookup(index, bareKey(p));
 }
 
 /**
  * Every version `typeUri` extends, transitively, nearest first: for 0.3
  * extends 0.2 extends 0.1, `["0.2", "0.1"]`.
  *
+ * `typeUri` may be in any SPEC §6.1 form. Each link is looked up under the
+ * same authority, form and slug as `typeUri` — only the version changes — so a
+ * chain never crosses authorities: a third-party specification's chain is read
+ * from its own declarations, never from a registry specification that happens
+ * to share its slug.
+ *
  * Defensive against a malformed index: the walk stops at a declaration that is
  * not strictly earlier within the same MAJOR (the build refuses those), and at
  * a cycle.
  */
-export function extendsChain(typeUri: string, index: ExtendsLookup = EXTENDS_BY_TYPE_URI): string[] {
-  const start = parseTypeUri(typeUri);
+export function extendsChain(typeUri: string, index: ExtendsLookup = defaultLookup): string[] {
+  const start = tryParseTypeUri(typeUri);
   if (start === null) return [];
   const chain: string[] = [];
   let current = start;
   for (;;) {
-    const next = lookup(index, `${PREFIX}${current.slug}/${current.version}`);
+    const next = lookup(index, bareKey(current));
     if (next === null) break;
-    const p = parseTypeUri(`${PREFIX}${current.slug}/${next}`)!;
-    if (p.major !== current.major || p.minor >= current.minor) break;
+    const m = VERSION_RE.exec(next)!;
+    const major = Number(m[1]);
+    const minor = Number(m[2]);
+    if (major !== current.major || minor >= current.minor) break;
     chain.push(next);
-    current = p;
+    current = typeUriWithVersion(current, major, minor);
   }
   return chain;
 }
@@ -154,13 +196,16 @@ export function receivedDocumentOf<P>(doc: TrustTaskDocument<P>): TrustTaskDocum
  * implements (`spec`, a generated `SPEC` or `RESPONSE_SPEC`).
  *
  * - Same Type URI as `spec.typeUri` — accepted unchanged.
- * - Same slug and variant, later version whose `extends` chain reaches
- *   `spec`'s version — accepted, payload pruned against `spec.payloadSchema`
- *   with {@link prunePayload}, `type` kept as received.
- * - Same slug and variant, any other version — refused `unsupportedVersion`.
- *   (Without a declaration a later MINOR SHOULD NOT be accepted: a draft may
- *   break in one.)
- * - A different specification or variant — refused `unsupportedType`.
+ * - Same specification (authority, form and slug) and variant, later version
+ *   whose `extends` chain reaches `spec`'s version — accepted, payload pruned
+ *   against `spec.payloadSchema` with {@link prunePayload}, `type` kept as
+ *   received.
+ * - Same specification and variant, any other version — refused
+ *   `unsupportedVersion`. (Without a declaration a later MINOR SHOULD NOT be
+ *   accepted: a draft may break in one.)
+ * - A different specification or variant — refused `unsupportedType`. The
+ *   same slug under another authority is another specification (SPEC §6.1),
+ *   so a third-party `x/0.3` never routes to a registry `x/0.1`, or back.
  * - Not a Trust Task document at all — refused `malformedRequest`.
  *
  * Proofs are not this function's business, and it neither reads nor alters
@@ -172,7 +217,7 @@ export function readForSpec<P>(
   spec: SpecPolicy,
   options: { index?: ExtendsLookup } = {},
 ): ReadForSpecResult<P> {
-  const index = options.index ?? EXTENDS_BY_TYPE_URI;
+  const index = options.index ?? defaultLookup;
   if (!isPlainObject(received) || typeof received.type !== "string" || !("payload" in received)) {
     return refused("malformedRequest", "not a Trust Task document (SPEC §4.2)");
   }
@@ -181,15 +226,17 @@ export function readForSpec<P>(
     return { kind: "accepted", doc: doc as TrustTaskDocument<P>, received: doc, extended: false };
   }
 
-  const got = parseTypeUri(doc.type);
-  const want = parseTypeUri(spec.typeUri);
-  if (got === null || want === null || got.slug !== want.slug || got.fragment !== want.fragment) {
+  const got = tryParseTypeUri(doc.type);
+  const want = tryParseTypeUri(spec.typeUri);
+  if (got === null || want === null || !sameSpecification(got, want) || got.variant !== want.variant) {
     return refused("unsupportedType", `unsupported Trust Task type ${JSON.stringify(doc.type)}`);
   }
-  if (got.version === want.version || !extendsChain(doc.type, index).includes(want.version)) {
+  const gotVersion = versionOf(got);
+  const wantVersion = versionOf(want);
+  if (gotVersion === wantVersion || !extendsChain(doc.type, index).includes(wantVersion)) {
     return refused(
       "unsupportedVersion",
-      `version ${got.version} of ${got.slug} is not supported; this consumer implements ${want.version}`,
+      `version ${gotVersion} of ${got.slug} is not supported; this consumer implements ${wantVersion}`,
     );
   }
 

package/src/_runtime/index.ts

@@ -68,9 +68,24 @@ export {
   type ProofVerifier,
 } from "./consume.js";
 
+export {
+  FRAMEWORK_RESERVED_SLUGS,
+  REGISTRY_TYPE_URI_AUTHORITY,
+  TypeUriError,
+  formatTypeUri,
+  parseTypeUri,
+  sameSpecification,
+  tryParseTypeUri,
+  typeUriWithVersion,
+  type TypeUri,
+  type TypeUriErrorKind,
+  type TypeUriVariant,
+} from "./type-uri.js";
+
 export { canonicalJson, sha256Hex } from "./canonical.js";
 
 export {
+  declareExtends,
   extendsChain,
   extendsOf,
   prunePayload,

package/src/_runtime/type-uri.ts

@@ -0,0 +1,252 @@
+/**
+ * Parsed Trust Task *Type URI* — every form SPEC.md §6.1 defines: the public
+ * registry's canonical form, and the two shapes a third-party specification
+ * (SPEC.md §6.5) may use under any other authority:
+ *
+ * ```text
+ * https://trusttasks.org/spec/<slug>/<MAJOR.MINOR>          public registry
+ * <prefix>/spec/<slug>/<MAJOR.MINOR>                        path form (https, DID URL, …)
+ * urn:<NID>:<prefix>:spec:<slug-segments>:<MAJOR.MINOR>     URN form
+ * ```
+ *
+ * each optionally followed by `#request` or `#response` (§4.4.1). A Type URI
+ * whose scheme is `urn` must use the URN form, and every other scheme the path
+ * form; `http` is refused in every form. {@link formatTypeUri} reproduces the
+ * parsed string exactly — a Type URI is a name, compared by its whole string
+ * (§6.1), so the authority is kept verbatim and is part of identity: the same
+ * slug under two authorities is two specifications.
+ *
+ * Hand-written. Mirrors `type_uri.rs` in trust-tasks-rs, whose unit tests are
+ * the source of most of the vectors in `test/type-uri.test.ts`.
+ */
+
+/** The `#request` / `#response` fragment of a Type URI (SPEC §4.4.1). */
+export type TypeUriVariant = "request" | "response";
+
+/** A parsed Type URI. Plain data; build a string back with {@link formatTypeUri}. */
+export interface TypeUri {
+  /**
+   * Everything before `/spec/` (path form) or `:spec:` (URN form), verbatim —
+   * e.g. `https://trusttasks.org`, `did:web:acme.example`, `urn:example:tasks`.
+   */
+  readonly authority: string;
+  /** `"path"` — `<authority>/spec/<slug>/<M.N>`; `"urn"` — `<authority>:spec:<seg>:…:<M.N>`. */
+  readonly form: "path" | "urn";
+  /** The slug, `/`-separated in both forms (`payments:settle` in a URN is `payments/settle`). */
+  readonly slug: string;
+  readonly major: number;
+  readonly minor: number;
+  /** The fragment, or `null` when absent (semantically equivalent to `"request"`, §4.4.1). */
+  readonly variant: TypeUriVariant | null;
+}
+
+/** Why a string is not a Type URI — the cases of Rust's `ParseTypeUriError`. */
+export type TypeUriErrorKind =
+  /** No scheme, a malformed one, or `http` (refused in every form, §6.1). */
+  | "scheme"
+  /** Neither the path form nor (for `urn:`) the URN form. */
+  | "shape"
+  /** The slug fails the §6.1 grammar. */
+  | "slug"
+  /** The slug is in the §6.1 reserved namespace and is not a framework slug. */
+  | "reservedSlug"
+  /** The version is not `MAJOR.MINOR` (§5.1). */
+  | "version"
+  /** A fragment other than `#request` / `#response`. */
+  | "fragment";
+
+/** Thrown by {@link parseTypeUri}. */
+export class TypeUriError extends Error {
+  readonly kind: TypeUriErrorKind;
+  /** The string that failed to parse (for `slug` / `version` / `fragment`, the offending part). */
+  readonly input: string;
+
+  constructor(kind: TypeUriErrorKind, input: string, message: string) {
+    super(message);
+    this.name = "TypeUriError";
+    this.kind = kind;
+    this.input = input;
+  }
+}
+
+/** The public registry's authority. */
+export const REGISTRY_TYPE_URI_AUTHORITY = "https://trusttasks.org";
+
+const SCHEME_RE = /^[A-Za-z][A-Za-z0-9+.-]*$/;
+const SEGMENT_RE = /^[a-z][a-z0-9]*(-[a-z0-9]+)*$/;
+const VERSION_RE = /^(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)$/;
+const U32_MAX = 0xffff_ffff;
+
+/**
+ * The framework slugs permitted inside the §6.1 reservation. A third
+ * hand-maintained copy of `#/properties/slug/anyOf[1]/enum` in
+ * `specs/spec.meta.schema.json` (Rust's `is_allowed_framework_slug` is the
+ * second); `test/type-uri.test.ts` reads that file and fails if they disagree.
+ */
+export const FRAMEWORK_RESERVED_SLUGS: readonly string[] = Object.freeze([
+  "trust-task",
+  "trust-task-error",
+  "trust-task-ok",
+  "trust-task-next-step",
+  "trust-task-discovery",
+  "trust-task-control",
+  "trust-ceremony-receipt",
+]);
+
+/** Whether `slug` is in the §6.1 reserved namespace `^trust-(task|ceremony)($|-|/)`. */
+function isReservedNamespace(slug: string): boolean {
+  const first = slug.split("/")[0]!;
+  return ["trust-task", "trust-ceremony"].some((stem) => first === stem || first.startsWith(`${stem}-`));
+}
+
+/** Throws unless `slug` satisfies the §6.1 grammar and reservation. */
+function checkSlug(slug: string): void {
+  if (slug.length === 0 || !slug.split("/").every((s) => SEGMENT_RE.test(s))) {
+    throw new TypeUriError("slug", slug, `slug ${JSON.stringify(slug)} does not satisfy SPEC §6.1 grammar`);
+  }
+  if (isReservedNamespace(slug) && !FRAMEWORK_RESERVED_SLUGS.includes(slug)) {
+    throw new TypeUriError("reservedSlug", slug, `slug ${JSON.stringify(slug)} is reserved per SPEC §6.1`);
+  }
+}
+
+function parseVersion(s: string): [number, number] {
+  const m = VERSION_RE.exec(s);
+  const major = m ? Number(m[1]) : NaN;
+  const minor = m ? Number(m[2]) : NaN;
+  if (!(major <= U32_MAX && minor <= U32_MAX)) {
+    throw new TypeUriError("version", s, `version ${JSON.stringify(s)} must be MAJOR.MINOR per SPEC §5.1`);
+  }
+  return [major, minor];
+}
+
+/**
+ * Parse a Type URI in any SPEC §6.1 form.
+ *
+ * @throws {TypeUriError} if `typeUri` is not one — its `kind` says why.
+ */
+export function parseTypeUri(typeUri: string): TypeUri {
+  if (typeof typeUri !== "string") {
+    throw new TypeUriError("scheme", String(typeUri), "a Type URI must be a string");
+  }
+  const hash = typeUri.indexOf("#");
+  const bare = hash < 0 ? typeUri : typeUri.slice(0, hash);
+  const fragment = hash < 0 ? null : typeUri.slice(hash + 1);
+  let variant: TypeUriVariant | null = null;
+  if (fragment !== null) {
+    if (fragment !== "request" && fragment !== "response") {
+      throw new TypeUriError(
+        "fragment",
+        fragment,
+        `only #request and #response fragments are permitted in a Type URI (got #${fragment})`,
+      );
+    }
+    variant = fragment;
+  }
+
+  // SPEC §6.1: any absolute URI, but never `http` — an `http` Type URI would
+  // normalise a transport-downgrade path for a consumer that dereferences it.
+  const colon = bare.indexOf(":");
+  const scheme = colon < 0 ? "" : bare.slice(0, colon);
+  if (!SCHEME_RE.test(scheme) || scheme.toLowerCase() === "http") {
+    throw new TypeUriError(
+      "scheme",
+      typeUri,
+      `Type URI must have a scheme other than http (SPEC §6.1): ${JSON.stringify(typeUri)}`,
+    );
+  }
+  const shape = (): TypeUriError =>
+    new TypeUriError(
+      "shape",
+      typeUri,
+      `Type URI must be <prefix>/spec/<slug>/<major.minor>, or ` +
+        `urn:<nid>:<prefix>:spec:<slug-segments>:<major.minor>: ${JSON.stringify(typeUri)}`,
+    );
+
+  let authority: string;
+  let slug: string;
+  let version: string;
+  let form: TypeUri["form"];
+  if (scheme.toLowerCase() === "urn") {
+    // `urn:<NID>:<prefix>:spec:<seg>:…:<MAJOR.MINOR>` — the slug is the
+    // segments between the first `:spec:` and the version.
+    const at = bare.indexOf(":spec:");
+    if (at < 0) throw shape();
+    authority = bare.slice(0, at);
+    const rest = bare.slice(at + ":spec:".length);
+    const parts = authority.split(":");
+    const nid = parts[1];
+    const ns = parts.slice(2).join(":");
+    if (!nid || !ns || rest.includes("/")) throw shape();
+    const cut = rest.lastIndexOf(":");
+    if (cut < 0) throw shape();
+    slug = rest.slice(0, cut).replace(/:/g, "/");
+    version = rest.slice(cut + 1);
+    form = "urn";
+  } else {
+    // `<prefix>/spec/<slug>/<MAJOR.MINOR>` — an https authority (with an
+    // optional path prefix), a DID URL, or any other scheme's prefix.
+    const at = bare.indexOf("/spec/");
+    if (at < 0) throw shape();
+    authority = bare.slice(0, at);
+    const afterScheme = authority.slice(scheme.length + 1);
+    if (
+      afterScheme.replace(/^\/+/, "").length === 0 ||
+      (scheme.toLowerCase() === "https" && !afterScheme.startsWith("//"))
+    ) {
+      throw shape();
+    }
+    const rest = bare.slice(at + "/spec/".length);
+    // The version is the final '/' segment; everything before it is the slug.
+    const cut = rest.lastIndexOf("/");
+    if (cut < 0) throw shape();
+    slug = rest.slice(0, cut);
+    version = rest.slice(cut + 1);
+    form = "path";
+  }
+
+  checkSlug(slug);
+  const [major, minor] = parseVersion(version);
+  return { authority, form, slug, major, minor, variant };
+}
+
+/** {@link parseTypeUri}, returning `null` instead of throwing. */
+export function tryParseTypeUri(typeUri: string): TypeUri | null {
+  try {
+    return parseTypeUri(typeUri);
+  } catch (e) {
+    if (e instanceof TypeUriError) return null;
+    throw e;
+  }
+}
+
+/**
+ * The string form of `uri`. For a value {@link parseTypeUri} returned, exactly
+ * the string it parsed.
+ */
+export function formatTypeUri(uri: TypeUri): string {
+  const v = `${uri.major}.${uri.minor}`;
+  const base =
+    uri.form === "urn"
+      ? `${uri.authority}:spec:${uri.slug.replace(/\//g, ":")}:${v}`
+      : `${uri.authority}/spec/${uri.slug}/${v}`;
+  return uri.variant === null ? base : `${base}#${uri.variant}`;
+}
+
+/**
+ * A sibling of `uri` at `major.minor`: the same authority, form, slug and
+ * variant, only the version changed. A declared-extension chain (SPEC §5.2)
+ * names only versions, so this is how it is walked — and why a chain never
+ * crosses authorities. (Rust's `TypeUri::with_version`.)
+ */
+export function typeUriWithVersion(uri: TypeUri, major: number, minor: number): TypeUri {
+  return { ...uri, major, minor };
+}
+
+/**
+ * Whether `a` and `b` name versions of the same specification: the same
+ * authority, form and slug. Two Type URIs with the same slug under different
+ * authorities are different specifications (SPEC §6.1).
+ */
+export function sameSpecification(a: TypeUri, b: TypeUri): boolean {
+  return a.authority === b.authority && a.form === b.form && a.slug === b.slug;
+}