mailschema 0.2.2 → 0.3.1

package/dist/core/artifacts.js

@@ -1,78 +1,30 @@
-// The bundled core artifacts and the validators built from them.
+// MAP 0.3's identifiers, limits and schema validation.
 import Ajv2020 from 'ajv/dist/2020.js';
-import { contractFormat, coreSchema, formsSchema } from "./bundled.js";
-export const MAP_PROFILE = 'https://mailschema.org/profiles/map/0.2';
-export const CORE_SCHEMA = 'https://mailschema.org/schemas/map-0.2.schema.json';
-export const FORMS_SCHEMA = 'https://mailschema.org/schemas/forms-0.1.schema.json';
-export const CONTRACT_FORMAT = 'https://mailschema.org/schemas/type-contract-0.2.schema.json';
-export const CONTEXT = 'https://mailschema.org/contexts/map-0.2.jsonld';
-export const JSON_SCHEMA_2020_12 = 'https://json-schema.org/draft/2020-12/schema';
-/** The schemas a contract may depend on without supplying them itself. */
-export const BUNDLED = new Map([
-    [CORE_SCHEMA, coreSchema],
-    [FORMS_SCHEMA, formsSchema],
-]);
+import addFormats from 'ajv-formats';
+export { coreSchema, contractSchema, implementationSchema } from "./bundled.js";
+export const PROFILE = 'https://mailschema.org/profiles/map/0.3';
+export const CONTEXT = 'https://mailschema.org/contexts/map-0.3.jsonld';
+/** The Content-Type of the MIME part that carries a description. */
+export const DESCRIPTION_MEDIA_TYPE = `application/ld+json; profile="${PROFILE}"`;
+export const DESCRIPTION_MAX_BYTES = 65536;
+export const CONTRACT_MAX_BYTES = 262144;
+/** The namespace of the initial effect vocabulary. */
+export const EFFECTS = 'https://mailschema.org/effects/';
+/** The formats MAP schemas may assert. Every implementation checks exactly these. */
+export const FORMATS = ['date', 'date-time', 'email', 'uri'];
 /**
- * JSON Schema 2020-12 as MAP reads it. Lexical forms are the core schema's patterns, so
- * `format` stays an annotation: format checkers differ between validators. References
- * resolve only against schemas already added, never over the network.
+ * JSON Schema 2020-12 as MAP reads it: the listed formats asserted, and references resolved
+ * only within the schema, never over the network. MAP's own rules decide which keywords and
+ * formats a contract may use; the validator adds no checks of its own beyond the vocabulary.
  * @internal
  */
 export function createValidator() {
-    const ajv = new Ajv2020({
-        allErrors: true,
-        strict: true,
-        strictRequired: false,
-        validateFormats: false,
-    });
-    // HTML autofill field names label form fields; they are annotations, not assertions.
-    ajv.addKeyword({ keyword: 'autocomplete', schemaType: 'string' });
-    // Only JSON Schema 2020-12 vocabulary keywords. Ajv also reads OpenAPI's `nullable`,
-    // which admits a null other validators refuse, and the earlier `dependencies` and
-    // `definitions`; strict mode now refuses them as unknown.
+    const ajv = new Ajv2020({ allErrors: true, strict: false });
+    addFormats(ajv, [...FORMATS]);
+    // Ajv also reads OpenAPI's `nullable` and the earlier `dependencies` and `definitions`.
     for (const keyword of ['nullable', 'dependencies', 'definitions'])
         ajv.removeKeyword(keyword);
-    for (const schema of BUNDLED.values())
-        ajv.addSchema(schema);
     return ajv;
 }
-const core = createValidator();
-/** A core or form fields definition by name, for the shared lexical vectors. */
-export const definition = (schema, name) => core.getSchema(`${schema}#/$defs/${name}`);
-/** Errors as `pointer message` lines, as the other MailSchema packages report them. */
-export function errorList(errors, prefix = '') {
-    return (errors ?? [])
-        .slice(0, 100)
-        .map((error) => `${prefix + error.instancePath || '/'} ${error.message}${error.keyword === 'required' ? `: ${error.params.missingProperty}` : ''}`);
-}
-const errorsOf = (validate, value) => validate(value) ? [] : errorList(validate.errors);
-const DOCUMENT = core.getSchema(CORE_SCHEMA);
-const DEFINITIONS = Object.fromEntries(['description', 'request', 'result', 'problem'].map((name) => [
-    name,
-    definition(CORE_SCHEMA, name),
-]));
-const DATE_TIME = new RegExp(coreSchema.$defs.dateTime.pattern, 'u');
-const REQUEST_ID = definition(CORE_SCHEMA, 'uuidUrn');
-const CONTRACT = core.compile(contractFormat);
-/** Checks a type contract against the contract format. */
-export const contractFormatErrors = (contract) => errorsOf(CONTRACT, contract);
-/** Checks any MAP 0.2 description, request, result or problem against the core schema. */
-export const mapErrors = (document) => errorsOf(DOCUMENT, document);
-/**
- * Checks a description against the core description definition only. A description of a
- * type the caller has no contract for can be checked this far.
- */
-export const descriptionErrors = (description) => errorsOf(DEFINITIONS.description, description);
-/** Checks a request against the core request definition. Its identifier stays free if it fails. */
-export const requestErrors = (request) => errorsOf(DEFINITIONS.request, request);
-/** Checks a result against the core result definition only. */
-export const resultErrors = (result) => errorsOf(DEFINITIONS.result, result);
-/** Checks a problem against the core problem definition, including its type, status and code. */
-export const problemErrors = (problem) => errorsOf(DEFINITIONS.problem, problem);
-/** Whether a value is a request identifier: the core UUID URN form. Only one names a result resource. */
-export const isRequestId = (value) => REQUEST_ID(value);
-/**
- * Whether a deadline, a core date-time plus `afterSeconds`, has been reached. Anything but
- * a core date-time counts as reached, so a mistake fails closed.
- */
-export const reached = (now, deadline, afterSeconds = 0) => !(DATE_TIME.test(deadline) && now.getTime() < Date.parse(deadline) + afterSeconds * 1000);
+/** Each validation error as its JSON Pointer and message. @internal */
+export const schemaErrors = (errors, prefix = '') => (errors ?? []).map((error) => `${prefix + error.instancePath || '/'}: ${error.message}`);

package/dist/core/bundled.d.ts

@@ -1,4 +1,4 @@
-import coreSchema from '../map-0.2.schema.json';
-import formsSchema from '../forms-0.1.schema.json';
-import contractFormat from '../type-contract-0.2.schema.json';
-export { coreSchema, formsSchema, contractFormat };
+import coreSchema from '../core.schema.json';
+import contractSchema from '../contract.schema.json';
+import implementationSchema from '../implementation.schema.json';
+export { coreSchema, contractSchema, implementationSchema };

package/dist/core/bundled.js

@@ -1,7 +1,7 @@
-// The core artifacts, by their canonical files. Package preparation points these three
-// imports at the package's own copies; no other line differs between the repository and
-// the npm package.
-import coreSchema from '../map-0.2.schema.json' with { type: 'json' };
-import formsSchema from '../forms-0.1.schema.json' with { type: 'json' };
-import contractFormat from '../type-contract-0.2.schema.json' with { type: 'json' };
-export { coreSchema, formsSchema, contractFormat };
+// The schemas the 0.3 profile record binds, by their canonical files. Package preparation
+// points these three imports at the package's own copies; no other line differs between the
+// repository and the npm package.
+import coreSchema from '../core.schema.json' with { type: 'json' };
+import contractSchema from '../contract.schema.json' with { type: 'json' };
+import implementationSchema from '../implementation.schema.json' with { type: 'json' };
+export { coreSchema, contractSchema, implementationSchema };

package/dist/core/contract.d.ts

@@ -1,66 +1,69 @@
-import type { ProblemCode } from './documents.ts';
-import type { InputError, JsonObject, MapDescription, MapRequest, TypeContract, TypeReference } from './types.ts';
-/** A type contract that fails its own checks or its pinned digest. */
-export declare class InvalidContract extends Error {
+import { type Description } from './description.ts';
+export interface Operation {
+    id: string;
+    name: string;
+    semantics: string;
+    effects: string[];
+    bindings: ('credential' | 'capability')[];
+    actors: ('human' | 'agent')[];
+    exactTerms: boolean;
+    inputSchema: Record<string, unknown> | null;
+    outcomes: Record<string, string>;
+    capability?: {
+        kind: CapabilityKind;
+        maxLifetimeSeconds: number;
+    };
 }
-/** Reasons the core assigns to the approval lifecycle. */
-export declare const APPROVAL_REASONS: readonly ["declined", "stale-target", "expired", "superseded"];
-/** A MAP problem a request earns before the service's own state is consulted. */
-export type RequestProblem = {
-    code: ProblemCode;
-    title: string;
-    detail: string;
+export interface ContractDocument {
+    id: string;
+    version: string;
+    profile: string;
+    name: string;
+    summary: string;
+    requirements: string[];
+    detailsSchema: Record<string, unknown>;
+    operations: Operation[];
+}
+export type CapabilityKind = keyof typeof CAPABILITY_KINDS;
+/** The capability binding's kinds: the exact effects each declares and its longest lifetime. */
+export declare const CAPABILITY_KINDS: {
+    readonly refusal: {
+        readonly effects: readonly ["refusal", "state"];
+        readonly maxLifetimeSeconds: 604800;
+    };
+    readonly 'protective-report': {
+        readonly effects: readonly ["protection", "state"];
+        readonly maxLifetimeSeconds: 259200;
+    };
+    readonly 'address-confirmation': {
+        readonly effects: readonly ["assertion", "state"];
+        readonly maxLifetimeSeconds: 86400;
+    };
 };
-/**
- * A type contract an implementation vendors, verified against the digest it was pinned by
- * and compiled once. It checks the descriptions, requests, inputs and results of that exact
- * type. The Registry has already applied the contract rules, such as portable patterns, to
- * the contract that digest names; loading refuses anything that would otherwise fail when a
- * request arrives.
- */
+/** Why the value is not a MAP 0.3 type contract, or no reasons. */
+export declare function contractErrors(value: unknown): string[];
+/** A valid contract with its digest and compiled schemas. */
 export declare class Contract {
     #private;
-    readonly document: TypeContract;
+    readonly document: ContractDocument;
+    /** `sha-256:` and the SHA-256 of the contract's RFC 8785 form. */
     readonly digest: string;
-    readonly requestSchema: JsonObject;
-    /**
-     * `digest` is the contract digest the implementation pinned; `dependencies` supplies, by
-     * URL, any pinned schema the package does not bundle.
-     */
-    constructor(contract: unknown, requestSchema: unknown, { digest: pinned, dependencies, }: {
-        digest: string;
-        dependencies?: Record<string, unknown>;
-    });
+    /** The contract, or InvalidDocument with every reason the value is not one. */
+    constructor(value: unknown);
+    /** The contract in the bytes or text, read as MAP JSON within the contract limit. */
+    static parse(input: string | Uint8Array): Contract;
     get id(): string;
     get version(): string;
-    /** The type reference a description and a request of this contract name exactly. */
-    get typeReference(): TypeReference;
-    operation(id: string): import("./types.ts").ContractOperation | undefined;
-    /** Whether completing the operation decides the interaction. */
-    isDecision(id: string): boolean;
-    /**
-     * Every rule a description must satisfy beyond the core schema, for the service that issues
-     * it and the client that receives it.
-     */
-    descriptionErrors(description: unknown): string[];
-    /**
-     * The checks a service makes on a request once it has resolved the description it issued,
-     * compared the description digest and established the caller: the exact type, an offered
-     * operation the authority permits, and expiry. Undefined when they pass. The service then
-     * applies its own state (a decided interaction, a stale target) and `inputErrors`, in that
-     * order, before any effect.
-     */
-    requestProblem(description: MapDescription, request: MapRequest, { now }: {
-        now: Date;
-    }): RequestProblem | undefined;
+    operation(id: string): Operation | undefined;
+    /** Why the details do not satisfy the contract's details schema, or no reasons. */
+    detailsErrors(details: unknown): string[];
+    /** Why the input is not acceptable for the operation, or no reasons. */
+    inputErrors(operationId: string, input: unknown): string[];
     /**
-     * Input problems for one request, each with a detail and a JSON Pointer into its input: the
-     * operation's input schema, then its field bindings against the description's details. Type
-     * rules a contract cannot express are the caller's.
+     * Why a valid description does not use this contract as it allows, or no reasons: it names
+     * this contract by identifier, version and digest; it offers only declared operations; a
+     * capability appears only where the contract permits one, at the service's origin and
+     * within the kind's lifetime; and its details satisfy the details schema.
      */
-    inputErrors(description: MapDescription, request: MapRequest): InputError[];
-    /** A request against the core request definition and this contract's request schema. */
-    requestErrors(request: unknown): string[];
-    /** The core result definition, then the output schema and reason the operation declares. */
-    resultErrors(result: unknown): string[];
+    descriptionErrors(description: Description): string[];
 }