mailschema 0.2.1 → 0.3.0

package/README.md

@@ -1,54 +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)
-
-The Mail Action Protocol 0.2 core artifacts, and local validation of MailSchema Registry contributions, with no network requests.
-
-[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
+npm install mailschema@0.3.0
 ```
 
-Node.js 22 or newer is required. The package is ESM and includes TypeScript declarations.
-
-## MAP 0.2 core artifacts
+## Check a description against its contract
 
 ```js
-import {
-  MAP_PROFILE,
-  getContractFormatSchema,
-  getFormsSchema,
-  getMapContext,
-  getMapSchema,
-} from 'mailschema';
-```
+import { readFile } from 'node:fs/promises';
+import { Contract, parseDescription } 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: a client obtains them from the [Registry catalogue](https://mailschema.org/registry/catalog.json) by digest. Processing MAP messages is outside this package; see the [profile](https://mailschema.org/specification/profile).
+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'));
+```
 
-## Registry data
+`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.
 
-```js
-import { assertContribution, contributionErrors, referenceErrors } from 'mailschema';
+## API
 
-const errors = contributionErrors(candidate);
-if (errors.length) console.error(errors);
-else assertContribution(candidate);
+- `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.
 
-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

@@ -0,0 +1,11 @@
+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"];

package/dist/core/artifacts.js

@@ -0,0 +1,30 @@
+// MAP 0.3's identifiers, limits and schema validation.
+import Ajv2020 from 'ajv/dist/2020.js';
+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: 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: 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);
+    return ajv;
+}
+/** 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

@@ -0,0 +1,4 @@
+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

@@ -0,0 +1,7 @@
+// 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

@@ -0,0 +1,69 @@
+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;
+    };
+}
+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;
+    };
+};
+/** 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: ContractDocument;
+    /** `sha-256:` and the SHA-256 of the contract's RFC 8785 form. */
+    readonly digest: string;
+    /** 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;
+    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[];
+    /**
+     * 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.
+     */
+    descriptionErrors(description: Description): string[];
+}