mailschema 0.2.2 → 0.3.0

package/README.md

@@ -1,138 +1,44 @@
-# MailSchema for JavaScript
+# mailschema
 
-[![npm](https://img.shields.io/npm/v/mailschema)](https://www.npmjs.com/package/mailschema)
-[![CI](https://github.com/mailschema/javascript/actions/workflows/test.yml/badge.svg)](https://github.com/mailschema/javascript/actions/workflows/test.yml)
-
-Mail Action Protocol 0.2 for JavaScript and TypeScript. The package parses, canonicalizes, digests and validates MAP documents, verifies the type contracts an implementation vendors, and builds results and problems. It also carries the MAP 0.2 core artifacts and validates MailSchema Registry contributions locally.
-
-It does not establish endpoint trust, verify email authentication, grant authority or send email. Possession mode needs DKIM and DMARC checks on the raw message, which this package leaves to the client.
-
-[Specification](https://mailschema.org/specification) · [Registry](https://mailschema.org/registry) · [Tools](https://mailschema.org/tools) · [Source](https://github.com/mailschema/javascript)
-
-## Install
+[Mail Action Protocol](https://mailschema.org) 0.3 for JavaScript. It parses and checks MAP descriptions, type contracts and Registry implementation records, and computes the RFC 8785 digests that identify contracts. The same code runs the MailSchema specification's own checks. It has no Node.js-only dependencies, so it also runs in browsers and workers.
 
 ```sh
-npm install mailschema
-```
-
-Node.js 22 or newer is required. The package is ESM and includes TypeScript declarations.
-
-## A service
-
-Vendor the exact contract and request schema your service implements, and pin the contract by the digest you reviewed. The package refuses any other contract.
-
-```ts
-import { readFileSync } from 'node:fs';
-import { Contract, digest } from 'mailschema';
-
-const read = (path: string) => JSON.parse(readFileSync(path, 'utf8'));
-const contract = new Contract(
-  read('mailschema/content-review-0.3.json'),
-  read('mailschema/content-review-0.3.schema.json'),
-  { digest: 'sha-256:…' },
-);
-```
-
-Before sending a description, check it against every rule of the core and the contract, and store its digest or keep it rebuildable from the interaction:
-
-```ts
-contract.descriptionErrors(description); // []
-digest(description); // 'sha-256:…'
+npm install mailschema@0.3.0
 ```
 
-When a request arrives, check it in this order. No step applies an effect for a problem, and a refusal before the description is resolved and its digest matched leaves the request identifier unclaimed:
-
-```ts
-import { isJsonRequest, parse, problem, requestErrors, result, resultUrl } from 'mailschema';
-import type { MapRequest } from 'mailschema';
-
-// Answer 415 unless isJsonRequest(contentType). Under possession authority, answer an
-// unknown capability with a plain 404 and a lapsed one with a plain 410 before reading
-// the body; under credential authority, authenticate the principal.
-const request = parse(body) as MapRequest; // throws InvalidDocument
-requestErrors(request); // any errors: invalid-request
-
-// Resolve the description you issued for request.interactionId. Refuse an unknown
-// interaction, or a request whose descriptionDigest is not digest(description).
+## Check a description against its contract
 
-// Request identifiers are claimed within your tenant: the account, or the capability.
-// If request.requestId is already claimed there, refuse another principal, and a principal
-// whose permission has been revoked, with an uncorrelated refused problem (problem()
-// without requestId). Answer any change to the request, compared by digest, with
-// idempotency-conflict. Otherwise settle the recorded result with settle() and return it,
-// or expired-interaction once retainUntil() has passed. Nothing is applied again.
-
-const refused = contract.requestProblem(description, request, { now: new Date() });
-// refused.code is unsupported-type, unsupported-operation or expired-interaction, with the
-// title and detail problem() takes. Then your own state: already-decided, or stale-target.
+```js
+import { readFile } from 'node:fs/promises';
+import { Contract, parseDescription } from 'mailschema';
 
-contract.inputErrors(description, request);
-// [{ detail: '…', pointer: '/feedback' }], a claimed invalid-request
+const contract = Contract.parse(await readFile('campaign-send-approval-0.1.json'));
+const description = parseDescription(await readFile('description.json'));
+const errors = contract.descriptionErrors(description);
+if (errors.length) throw new Error(errors.join('\n'));
 ```
 
-Then apply the approval lifecycle or the effect, and record the result:
-
-```ts
-result(request, {
-  state: 'accepted',
-  target: description.target,
-  resultUrl: resultUrl(description, request.requestId),
-  recordedAt: new Date(),
-  output: { feedbackRecorded: true, feedbackId: 'fb-1' },
-});
-```
+`parseDescription` reads the bytes as MAP JSON (strict I-JSON within 64 KiB) and checks the core rules, or throws `InvalidDocument` with every reason. Obtain contracts from a catalogue you configure and pin them by digest; a message never chooses one.
 
 ## API
 
-| Call                                                                          | Does                                                                                                                                                                                                                                                                                             |
-| ----------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `parse(text \| bytes)`                                                        | Parses a MAP document as I-JSON within the core limits, or throws `InvalidDocument`                                                                                                                                                                                                              |
-| `canonicalize(value)`, `digest(value)`                                        | RFC 8785 canonical JSON, and `sha-256:` over it                                                                                                                                                                                                                                                  |
-| `mapErrors(document)`                                                         | Checks a description, request, result or problem against the core schema                                                                                                                                                                                                                         |
-| `descriptionErrors`, `requestErrors`, `resultErrors`, `problemErrors`         | Check one document against its core definition only                                                                                                                                                                                                                                              |
-| `new Contract(contract, requestSchema, { digest, dependencies })`             | Checks the contract's format and profile, refuses any contract but the one pinned by `digest`, checks its pinned dependencies and request schema, and compiles every validator once, or throws `InvalidContract`; `dependencies` supplies, by URL, any pinned schema the package does not bundle |
-| `contract.descriptionErrors(description)`                                     | Checks a description against every rule of the core and the contract                                                                                                                                                                                                                             |
-| `contract.requestProblem(description, request, { now })`                      | The exact type, an offered operation the authority permits, and expiry, as a problem code, title and detail, or undefined                                                                                                                                                                        |
-| `contract.inputErrors(description, request)`                                  | Checks an operation's input and field bindings, with JSON Pointers into `input`                                                                                                                                                                                                                  |
-| `contract.requestErrors(request)`, `contract.resultErrors(result)`            | Check a request against the core and the request schema, and a result against the core, the declared output schema and the declared reason                                                                                                                                                       |
-| `contract.typeReference`, `contract.operation(id)`, `contract.isDecision(id)` | The type reference descriptions and requests name, one of its operations, and whether completing it decides the interaction                                                                                                                                                                      |
-| `result`, `transition`, `problem`                                             | Build results, state transitions and problems with their correlation members, or throw rather than return a document the core refuses. A problem stays within the core limits                                                                                                                    |
-| `resultUrl`, `resultStatus`, `isRequestId`                                    | The result resource of a request, a result's HTTP status, and whether a value is a request identifier, the only thing a result URL names                                                                                                                                                         |
-| `isJsonRequest(contentType)`                                                  | Whether a `Content-Type` admits a request rather than a 415                                                                                                                                                                                                                                      |
-| `DESCRIPTION_MEDIA_TYPE`, `isDescriptionPart(mediaType, profileParameter)`    | The `Content-Type` of the part that carries a description, and whether a designated part is labelled with this profile                                                                                                                                                                           |
-| `retainUntil`, `settle`, `reached`                                            | Result retention, the expiry of an undecided approval, and whether a deadline has passed                                                                                                                                                                                                         |
-| `capability(description)`, `writtenPath(url)`                                 | The possession capability: the last segment of the execution URL's path as written                                                                                                                                                                                                               |
+- `parse(input, maxBytes)`, `canonicalize(value)`, `digest(value)`: MAP JSON and RFC 8785 digests.
+- `descriptionErrors(value)`, `parseDescription(input)`: the core description rules.
+- `new Contract(value)`, `Contract.parse(input)`: a checked contract with `digest`, `operation(id)`, `detailsErrors(details)`, `inputErrors(operationId, input)` and `descriptionErrors(description)`.
+- `contractErrors(value)`: why a value is not a contract, including schema keywords, formats and patterns every implementation can enforce alike.
+- `implementationErrors(value)`, `parseImplementation(input)`: Registry implementation records.
+- `PROFILE`, `CONTEXT`, `DESCRIPTION_MEDIA_TYPE`, `EFFECTS`, `CAPABILITY_KINDS` and the size limits.
 
-Type rules a contract cannot express, such as a meeting slot being one of the slots offered, belong to each type's implementation. Validation uses Ajv with JSON Schema 2020-12. Lexical forms are core schema patterns, so `format` is never asserted, and references resolve only against pinned schemas, never over the network.
-
-## MAP 0.2 core artifacts
-
-```js
-import { getContractFormatSchema, getFormsSchema, getMapContext, getMapSchema } from 'mailschema';
-```
-
-Each is byte-identical to the file the [profile record](https://mailschema.org/profiles/map/0.2.json) binds by SHA-256, and is also exported raw as `mailschema/map-0.2.schema.json`, `mailschema/map-0.2.jsonld`, `mailschema/type-contract-0.2.schema.json` and `mailschema/forms-0.1.schema.json`. Type contracts are not bundled: an implementation vendors the contracts it supports, and `Contract` verifies them by digest.
-
-## Registry data
-
-```js
-import { assertContribution, contributionErrors, referenceErrors } from 'mailschema';
-
-const errors = contributionErrors(candidate);
-if (errors.length) console.error(errors);
-else assertContribution(candidate);
-
-const referenceProblems = referenceErrors(candidate, catalog);
-```
+The profile record, context and schemas are exported byte for byte: `mailschema/profile.json`, `mailschema/context.jsonld`, `mailschema/core.schema.json`, `mailschema/contract.schema.json` and `mailschema/implementation.schema.json`.
 
-`assertTypeRecord` and `getRecordSchema` handle expanded Registry records. Reference checks use a catalogue supplied by the caller; the package never fetches one.
+## Command line
 
 ```sh
-npx mailschema check contribution.json
-npx mailschema check record.json --record
-npx mailschema schema --map
+npx mailschema@0.3.0 contract campaign-send-approval-0.1.json
+npx mailschema@0.3.0 description description.json --contract campaign-send-approval-0.1.json
+npx mailschema@0.3.0 implementation record.json
 ```
 
-## Trust boundary
+Checking does not authenticate a message, establish a service's authority or perform an action. Those belong to the implementation, under the [specification](https://mailschema.org/specification/core).
 
-A valid document is structured input. Validation does not authenticate a service, grant authority or establish product conformance. The CLI reads one local file of at most 256 KiB and does not upload or modify it. Package versions and MAP profile versions advance independently. MIT licensed.
+Source: [mailschema/javascript](https://github.com/mailschema/javascript). License: MIT.

package/bin/mailschema.js

@@ -1,72 +1,59 @@
 #!/usr/bin/env node
-import { open } from 'node:fs/promises';
+import { readFile, stat } from 'node:fs/promises';
 import { parseArgs } from 'node:util';
 import {
-  assertContribution,
-  assertTypeRecord,
-  getContractFormatSchema,
-  getContributionSchema,
-  getFormsSchema,
-  getMapContext,
-  getMapSchema,
-  getRecordSchema,
+  Contract,
+  CONTRACT_MAX_BYTES,
+  InvalidDocument,
+  parseDescription,
+  parseImplementation,
 } from '../dist/index.js';
 
-const help = `MailSchema Registry tools
+const help = `Mail Action Protocol 0.3 checks
 
-  mailschema check <file.json> [--record]
-  mailschema schema [--record | --map | --context | --contract-format | --forms]
+  mailschema contract <contract.json>
+  mailschema description <description.json> [--contract <contract.json>]
+  mailschema implementation <record.json>
 
-check validates a Registry contribution, or with --record an expanded record,
-locally. schema prints a bundled schema: the contribution schema by default, or
-a MAP 0.2 core artifact. No files are uploaded or changed.`;
+contract checks a type contract and prints its digest. description checks a
+description and, with --contract, that it uses that contract as it allows.
+implementation checks a Registry implementation record. Nothing is uploaded
+or changed.`;
 
-const schemas = {
-  record: getRecordSchema,
-  map: getMapSchema,
-  context: getMapContext,
-  'contract-format': getContractFormatSchema,
-  forms: getFormsSchema,
-};
+async function read(path) {
+  const info = await stat(path);
+  if (!info.isFile() || info.size > CONTRACT_MAX_BYTES)
+    throw new Error(`Expected a JSON file of at most ${CONTRACT_MAX_BYTES} bytes.`);
+  return new Uint8Array(await readFile(path));
+}
+
+function report(errors) {
+  if (!errors.length) return;
+  throw new InvalidDocument('Not valid.', errors);
+}
 
 try {
   const { values, positionals } = parseArgs({
     allowPositionals: true,
-    options: {
-      ...Object.fromEntries(Object.keys(schemas).map((name) => [name, { type: 'boolean' }])),
-      help: { type: 'boolean', short: 'h' },
-    },
+    options: { contract: { type: 'string' }, help: { type: 'boolean', short: 'h' } },
   });
   const [command, path, ...extra] = positionals;
-  const chosen = Object.keys(schemas).filter((name) => values[name]);
-  if (chosen.length > 1) throw new Error('Choose only one schema.');
   if (values.help || !command) console.log(help);
-  else if (command === 'schema' && !path && !extra.length)
-    console.log(JSON.stringify((schemas[chosen[0]] ?? getContributionSchema)(), null, 2));
-  else if (
-    command === 'check' &&
-    path &&
-    !extra.length &&
-    chosen.every((name) => name === 'record')
-  ) {
-    const file = await open(path, 'r');
-    let value;
-    try {
-      const info = await file.stat();
-      if (!info.isFile() || info.size > 256 * 1024)
-        throw new Error('Expected a JSON file no larger than 256 KiB.');
-      const bytes = Buffer.alloc(256 * 1024 + 1);
-      const { bytesRead } = await file.read(bytes, 0, bytes.length, 0);
-      if (bytesRead > 256 * 1024) throw new Error('JSON file exceeds 256 KiB.');
-      value = JSON.parse(bytes.subarray(0, bytesRead).toString('utf8'));
-    } finally {
-      await file.close();
-    }
-    if (values.record) assertTypeRecord(value);
-    else assertContribution(value);
-    console.log(`Valid MailSchema ${values.record ? 'type record' : 'contribution'}.`);
+  else if (!path || extra.length || (values.contract && command !== 'description'))
+    throw new Error(help);
+  else if (command === 'contract') {
+    const contract = Contract.parse(await read(path));
+    console.log(`Valid type contract ${contract.id} ${contract.version}\n${contract.digest}`);
+  } else if (command === 'description') {
+    const description = parseDescription(await read(path));
+    if (values.contract)
+      report(Contract.parse(await read(values.contract)).descriptionErrors(description));
+    console.log(`Valid MAP 0.3 description ${description['@id']}`);
+  } else if (command === 'implementation') {
+    const record = parseImplementation(await read(path));
+    console.log(`Valid implementation record for ${record.service}`);
   } else throw new Error(help);
 } catch (error) {
-  console.error(error instanceof Error ? error.message : String(error));
+  console.error(error instanceof InvalidDocument ? error.errors.join('\n') : error.message);
   process.exitCode = 1;
 }

package/dist/context.jsonld

@@ -0,0 +1,50 @@
+{
+  "@context": {
+    "@version": 1.1,
+    "@protected": true,
+    "@vocab": "https://mailschema.org/vocab/map/0.3#",
+    "MailAction": "https://mailschema.org/vocab/map/0.3#MailAction",
+    "profile": {
+      "@id": "profile",
+      "@type": "@id"
+    },
+    "type": {
+      "@id": "type",
+      "@type": "@json"
+    },
+    "service": {
+      "@id": "service",
+      "@type": "@json"
+    },
+    "subject": {
+      "@id": "subject",
+      "@type": "@json"
+    },
+    "terms": {
+      "@id": "terms",
+      "@type": "@json"
+    },
+    "details": {
+      "@id": "details",
+      "@type": "@json"
+    },
+    "operations": {
+      "@id": "operations",
+      "@type": "@json"
+    },
+    "human": {
+      "@id": "human",
+      "@type": "@json"
+    },
+    "recipient": "recipient",
+    "inLanguage": "inLanguage",
+    "issuedAt": {
+      "@id": "issuedAt",
+      "@type": "http://www.w3.org/2001/XMLSchema#dateTime"
+    },
+    "expiresAt": {
+      "@id": "expiresAt",
+      "@type": "http://www.w3.org/2001/XMLSchema#dateTime"
+    }
+  }
+}

package/dist/contract.schema.json

@@ -0,0 +1,206 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://mailschema.org/artifacts/map-0.3/schemas/contract.schema.json",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "id",
+    "version",
+    "profile",
+    "name",
+    "summary",
+    "requirements",
+    "detailsSchema",
+    "operations"
+  ],
+  "properties": {
+    "id": {
+      "type": "string",
+      "minLength": 1,
+      "format": "uri",
+      "pattern": "^https://",
+      "maxLength": 2048
+    },
+    "version": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 64
+    },
+    "profile": {
+      "const": "https://mailschema.org/profiles/map/0.3"
+    },
+    "name": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 2048
+    },
+    "summary": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 2048
+    },
+    "requirements": {
+      "type": "array",
+      "items": {
+        "type": "string",
+        "minLength": 1,
+        "maxLength": 2048
+      },
+      "minItems": 1,
+      "maxItems": 64
+    },
+    "detailsSchema": {
+      "type": "object"
+    },
+    "operations": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": [
+          "id",
+          "name",
+          "semantics",
+          "effects",
+          "bindings",
+          "actors",
+          "exactTerms",
+          "inputSchema",
+          "outcomes"
+        ],
+        "properties": {
+          "id": {
+            "type": "string",
+            "minLength": 1,
+            "pattern": "^[a-z][a-z0-9-]{0,63}$"
+          },
+          "name": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 2048
+          },
+          "semantics": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 2048
+          },
+          "effects": {
+            "type": "array",
+            "items": {
+              "type": "string",
+              "minLength": 1,
+              "format": "uri",
+              "pattern": "^https://"
+            },
+            "minItems": 1,
+            "maxItems": 32,
+            "uniqueItems": true
+          },
+          "bindings": {
+            "type": "array",
+            "items": {
+              "enum": [
+                "credential",
+                "capability"
+              ]
+            },
+            "minItems": 1,
+            "maxItems": 2,
+            "uniqueItems": true
+          },
+          "actors": {
+            "type": "array",
+            "items": {
+              "enum": [
+                "human",
+                "agent"
+              ]
+            },
+            "minItems": 1,
+            "maxItems": 2,
+            "uniqueItems": true
+          },
+          "exactTerms": {
+            "type": "boolean"
+          },
+          "inputSchema": {
+            "type": [
+              "object",
+              "null"
+            ]
+          },
+          "outcomes": {
+            "type": "object",
+            "minProperties": 1,
+            "propertyNames": {
+              "pattern": "^[a-z][a-z0-9-]{0,63}$"
+            },
+            "additionalProperties": {
+              "type": "string",
+              "minLength": 1,
+              "maxLength": 2048
+            }
+          },
+          "capability": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": [
+              "kind",
+              "maxLifetimeSeconds"
+            ],
+            "properties": {
+              "kind": {
+                "enum": [
+                  "refusal",
+                  "protective-report",
+                  "address-confirmation"
+                ]
+              },
+              "maxLifetimeSeconds": {
+                "type": "integer",
+                "minimum": 1,
+                "maximum": 604800
+              }
+            }
+          }
+        },
+        "allOf": [
+          {
+            "if": {
+              "properties": {
+                "bindings": {
+                  "contains": {
+                    "const": "capability"
+                  },
+                  "type": "array"
+                }
+              }
+            },
+            "then": {
+              "required": [
+                "capability"
+              ],
+              "properties": {
+                "inputSchema": {
+                  "type": "null"
+                },
+                "exactTerms": {
+                  "const": true
+                }
+              }
+            },
+            "else": {
+              "not": {
+                "required": [
+                  "capability"
+                ]
+              }
+            }
+          }
+        ]
+      },
+      "minItems": 1,
+      "maxItems": 32
+    }
+  }
+}

package/dist/core/artifacts.d.ts

@@ -1,36 +1,11 @@
-import { type ErrorObject, type ValidateFunction } from 'ajv/dist/2020.js';
-import type { JsonObject } from './types.ts';
-export declare const MAP_PROFILE = "https://mailschema.org/profiles/map/0.2";
-export declare const CORE_SCHEMA = "https://mailschema.org/schemas/map-0.2.schema.json";
-export declare const FORMS_SCHEMA = "https://mailschema.org/schemas/forms-0.1.schema.json";
-export declare const CONTRACT_FORMAT = "https://mailschema.org/schemas/type-contract-0.2.schema.json";
-export declare const CONTEXT = "https://mailschema.org/contexts/map-0.2.jsonld";
-export declare 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 declare const BUNDLED: ReadonlyMap<string, JsonObject>;
-/** A core or form fields definition by name, for the shared lexical vectors. */
-export declare const definition: (schema: string, name: string) => ValidateFunction;
-/** Errors as `pointer message` lines, as the other MailSchema packages report them. */
-export declare function errorList(errors: ErrorObject[] | null | undefined, prefix?: string): string[];
-/** Checks a type contract against the contract format. */
-export declare const contractFormatErrors: (contract: unknown) => string[];
-/** Checks any MAP 0.2 description, request, result or problem against the core schema. */
-export declare const mapErrors: (document: unknown) => string[];
-/**
- * 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 declare const descriptionErrors: (description: unknown) => string[];
-/** Checks a request against the core request definition. Its identifier stays free if it fails. */
-export declare const requestErrors: (request: unknown) => string[];
-/** Checks a result against the core result definition only. */
-export declare const resultErrors: (result: unknown) => string[];
-/** Checks a problem against the core problem definition, including its type, status and code. */
-export declare const problemErrors: (problem: unknown) => string[];
-/** Whether a value is a request identifier: the core UUID URN form. Only one names a result resource. */
-export declare const isRequestId: (value: unknown) => boolean;
-/**
- * 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 declare const reached: (now: Date, deadline: string, afterSeconds?: number) => boolean;
+export { coreSchema, contractSchema, implementationSchema } from './bundled.ts';
+export declare const PROFILE = "https://mailschema.org/profiles/map/0.3";
+export declare const CONTEXT = "https://mailschema.org/contexts/map-0.3.jsonld";
+/** The Content-Type of the MIME part that carries a description. */
+export declare const DESCRIPTION_MEDIA_TYPE = "application/ld+json; profile=\"https://mailschema.org/profiles/map/0.3\"";
+export declare const DESCRIPTION_MAX_BYTES = 65536;
+export declare const CONTRACT_MAX_BYTES = 262144;
+/** The namespace of the initial effect vocabulary. */
+export declare const EFFECTS = "https://mailschema.org/effects/";
+/** The formats MAP schemas may assert. Every implementation checks exactly these. */
+export declare const FORMATS: readonly ["date", "date-time", "email", "uri"];