@kashscript/lexicons 0.1.0

package/package.json

@@ -0,0 +1,80 @@
+{
+  "name": "@kashscript/lexicons",
+  "version": "0.1.0",
+  "description": "Zero-dependency lexicon framework — envelope, schema DSL, registry, validator. Agnostic core; domain content ships as opt-in extensions.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./envelope": {
+      "types": "./dist/envelope.d.ts",
+      "import": "./dist/envelope.js",
+      "default": "./dist/envelope.js"
+    },
+    "./schema": {
+      "types": "./dist/schema.d.ts",
+      "import": "./dist/schema.js",
+      "default": "./dist/schema.js"
+    },
+    "./registry": {
+      "types": "./dist/registry.d.ts",
+      "import": "./dist/registry.js",
+      "default": "./dist/registry.js"
+    },
+    "./engine": {
+      "types": "./dist/engine.d.ts",
+      "import": "./dist/engine.js",
+      "default": "./dist/engine.js"
+    },
+    "./json-schema": {
+      "types": "./dist/json-schema.d.ts",
+      "import": "./dist/json-schema.js",
+      "default": "./dist/json-schema.js"
+    },
+    "./semver": {
+      "types": "./dist/semver.d.ts",
+      "import": "./dist/semver.js",
+      "default": "./dist/semver.js"
+    },
+    "./extensions/social": {
+      "types": "./dist/extensions/social.d.ts",
+      "import": "./dist/extensions/social.js",
+      "default": "./dist/extensions/social.js"
+    },
+    "./extensions/trade": {
+      "types": "./dist/extensions/trade.d.ts",
+      "import": "./dist/extensions/trade.js",
+      "default": "./dist/extensions/trade.js"
+    },
+    "./extensions/zkp": {
+      "types": "./dist/extensions/zkp.d.ts",
+      "import": "./dist/extensions/zkp.js",
+      "default": "./dist/extensions/zkp.js"
+    }
+  },
+  "sideEffects": false,
+  "files": [
+    "dist",
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc --noEmit",
+    "clean": "rm -rf dist .turbo"
+  },
+  "devDependencies": {
+    "typescript": "^5.6.3"
+  },
+  "license": "Apache-2.0",
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  }
+}

package/src/engine.ts

@@ -0,0 +1,141 @@
+/**
+ * Validation Engine — pure-function entry points that compose a registry
+ * with the schema engine.
+ *
+ *  validateEvent(event, registry)
+ *    1. Validate the Kash-Event envelope shape (header + signature; body deferred).
+ *    2. Parse the declared Lexicon ID from `header.lexicon`.
+ *    3. Look up a forward-compatible registered schema via the registry.
+ *    4. Deep-validate `body` against the registered schema.
+ *
+ *  getSchemaDefinition(lexiconId, registry)
+ *    Returns a JSON-Schema Draft-2020-12 representation of the body schema for
+ *    a given Lexicon ID. Used by Oreoasis (and any external AI/tooling) to
+ *    "teach" itself a new data type at runtime without code changes.
+ *
+ * Both functions are pure and stateless. No network, no crypto, no storage.
+ */
+
+import { BASE_ENVELOPE_SCHEMA, type KashEvent } from "./envelope";
+import { toJsonSchema, type JsonSchema } from "./json-schema";
+import type { LexiconRegistry } from "./registry";
+import {
+  validate,
+  type Schema,
+  type ValidationError,
+  type ValidationResult,
+} from "./schema";
+import { parseLexiconId } from "./semver";
+
+/**
+ * Full envelope-and-body validation against a registry.
+ *
+ * Returns the typed `KashEvent<Body>` on success, or a flat list of errors
+ * keyed by JSON-pointer-style path on failure. All errors are collected
+ * (not fail-fast) so the caller can render a complete diagnostic.
+ */
+export function validateEvent<Body = unknown>(
+  event: unknown,
+  registry: LexiconRegistry,
+): ValidationResult<KashEvent<Body>> {
+  // Stage 1 — envelope shape (header + signature; body permissive).
+  const envResult = validate<KashEvent>(BASE_ENVELOPE_SCHEMA, event);
+  if (!envResult.ok) return envResult as ValidationResult<KashEvent<Body>>;
+
+  const env = envResult.value;
+
+  // Stage 2 — parse declared Lexicon ID.
+  const parsed = parseLexiconId(env.header.lexicon);
+  if (parsed === null) {
+    return failOne(["header", "lexicon"], "unparseable lexicon ID", env.header.lexicon);
+  }
+
+  // Stage 3 — resolve from registry (forward-compatible within major).
+  const entry = registry.resolve(parsed.nsid, parsed.semver);
+  if (!entry) {
+    return failOne(
+      ["header", "lexicon"],
+      `no registered lexicon supports "${env.header.lexicon}"`,
+      env.header.lexicon,
+    );
+  }
+
+  // Stage 4 — deep-validate body against the registered schema.
+  const bodyResult = validate(entry.bodySchema, env.body);
+  if (!bodyResult.ok) {
+    const rebased: ValidationError[] = bodyResult.errors.map((e) => ({
+      path: ["body", ...e.path],
+      message: e.message,
+      received: e.received,
+    }));
+    return { ok: false, errors: rebased };
+  }
+
+  return { ok: true, value: env as KashEvent<Body> };
+}
+
+/**
+ * Validate a raw body against a registered lexicon — bypasses the envelope.
+ * Useful when constructing a record locally before signing it.
+ */
+export function validateBody<Body = unknown>(
+  lexiconId: string,
+  body: unknown,
+  registry: LexiconRegistry,
+): ValidationResult<Body> {
+  const parsed = parseLexiconId(lexiconId);
+  if (parsed === null) {
+    return failOne([], `invalid lexicon ID "${lexiconId}"`, lexiconId);
+  }
+  const entry = registry.resolve(parsed.nsid, parsed.semver);
+  if (!entry) {
+    return failOne([], `no registered lexicon supports "${lexiconId}"`, lexiconId);
+  }
+  return validate<Body>(entry.bodySchema, body);
+}
+
+/**
+ * Return a JSON-Schema-Draft-2020-12 representation of the registered lexicon.
+ *
+ * Used by Oreoasis (and any external AI / tooling) to load a previously
+ * unknown lexicon's structure at runtime. The returned object includes
+ * `$schema`, `$id`, `title`, and `description` metadata.
+ *
+ * Returns `null` if the Lexicon ID is malformed or no compatible entry is
+ * registered.
+ */
+export function getSchemaDefinition(
+  lexiconId: string,
+  registry: LexiconRegistry,
+): JsonSchema | null {
+  const parsed = parseLexiconId(lexiconId);
+  if (parsed === null) return null;
+  const entry = registry.resolve(parsed.nsid, parsed.semver);
+  if (!entry) return null;
+
+  const body = toJsonSchema(entry.bodySchema);
+  const out: Record<string, unknown> = {
+    $schema:     "https://json-schema.org/draft/2020-12/schema",
+    $id:         `https://kashscript.com/lexicons/${entry.id}`,
+    title:       entry.title ?? entry.id,
+    description: entry.description ?? `Body schema for ${entry.id}`,
+    ...body,
+  };
+  return out;
+}
+
+/** Return the raw internal Schema (not JSON-Schema) for advanced consumers. */
+export function getRawSchema(lexiconId: string, registry: LexiconRegistry): Schema | null {
+  const parsed = parseLexiconId(lexiconId);
+  if (parsed === null) return null;
+  const entry = registry.resolve(parsed.nsid, parsed.semver);
+  return entry?.bodySchema ?? null;
+}
+
+function failOne(
+  path: readonly (string | number)[],
+  message: string,
+  received: unknown,
+): { ok: false; errors: readonly ValidationError[] } {
+  return { ok: false, errors: [{ path, message, received }] };
+}

package/src/envelope.ts

@@ -0,0 +1,128 @@
+/**
+ * The Kash-Event Envelope.
+ *
+ * Every record stored in a PDS conforms to this shape. The envelope is
+ * lexicon-agnostic — only the `body` shape is governed by a specific lexicon.
+ * Signatures are bound by a Domain-Separation Tag (DST) to prevent
+ * cross-protocol replay (see Identity Protocol §5.5).
+ */
+
+import { S, type ObjectSchema, type Schema } from "./schema";
+import {
+  KASH_RECORD_DST,
+  type CID,
+  type DID,
+  type Iso8601,
+  type KashRecordDST,
+  type LexiconId,
+  type Multibase,
+  type SignatureAlgorithm,
+} from "./types";
+
+/* ── interfaces ─────────────────────────────────────────────────── */
+
+/** Cryptographic signature produced by a Signer under a `purpose: "active"` key. */
+export interface KashSignature {
+  /** verificationMethod id, e.g., "did:kash:5g7q…#sig-1". */
+  readonly kid: string;
+  /** Must match the verification method's `algorithm` field at verification time. */
+  readonly alg: SignatureAlgorithm;
+  /** Multibase-encoded signature bytes (z-prefix, base58-btc). */
+  readonly sig: Multibase;
+  /** Fixed DST: "kash-record-v1\n". Prevents cross-protocol replay. */
+  readonly dst: KashRecordDST;
+}
+
+/** Header carried by every record, lexicon-agnostic. */
+export interface KashHeader {
+  /** Author DID. */
+  readonly did: DID;
+  /** Lexicon ID — <nsid>@<semver>. */
+  readonly lexicon: LexiconId;
+  /** Issued-at timestamp (ISO-8601 with offset). */
+  readonly iat: Iso8601;
+  /** Per-record nonce — 32-128 hex chars (≥128 bits of entropy). */
+  readonly nonce: string;
+  /** CID of the canonicalized body (computed at envelope-build time). */
+  readonly cid: CID;
+  /** Optional monotonic sequence within this (did, nsid) collection. */
+  readonly seq?: number;
+  /** Optional CID of the previous record in the same collection. */
+  readonly prev?: CID;
+  /** Optional record key — opaque, app-chosen. */
+  readonly rkey?: string;
+}
+
+/** Standard Kash-Event envelope. Every PDS record IS a KashEvent<Body>. */
+export interface KashEvent<Body = unknown> {
+  readonly header: KashHeader;
+  readonly body: Body;
+  readonly signature: KashSignature;
+}
+
+/* ── runtime schemas ────────────────────────────────────────────── */
+
+export const SIGNATURE_SCHEMA: ObjectSchema = S.object(
+  {
+    kid: S.string({ minLength: 1, maxLength: 256 }),
+    alg: S.enum("ed25519", "es256", "bls12-381-g2"),
+    sig: S.string({ format: "multibase" }),
+    dst: S.literal(KASH_RECORD_DST),
+  },
+  ["kid", "alg", "sig", "dst"],
+);
+
+export const HEADER_SCHEMA: ObjectSchema = S.object(
+  {
+    did:     S.string({ format: "did-ks" }),
+    lexicon: S.string({ format: "lexicon-id" }),
+    iat:     S.string({ format: "iso8601" }),
+    nonce:   S.string({ minLength: 32, maxLength: 128, pattern: /^[0-9a-f]+$/ }),
+    cid:     S.string({ format: "cid" }),
+    seq:     S.optional(S.number({ integer: true, min: 0 })),
+    prev:    S.optional(S.string({ format: "cid" })),
+    rkey:    S.optional(S.string({ minLength: 1, maxLength: 128 })),
+  },
+  ["did", "lexicon", "iat", "nonce", "cid"],
+);
+
+/** Envelope schema parameterised by the body's schema. */
+export function envelopeSchema(body: Schema): ObjectSchema {
+  return S.object(
+    {
+      header: HEADER_SCHEMA,
+      body,
+      signature: SIGNATURE_SCHEMA,
+    },
+    ["header", "body", "signature"],
+  );
+}
+
+/** Envelope schema that accepts any body (used during pre-lexicon shape validation). */
+export const BASE_ENVELOPE_SCHEMA: ObjectSchema = envelopeSchema(S.any());
+
+/* ── shared record-reference shape ───────────────────────────────
+ *
+ * `RecordRef` points to another record by (CID, AT-URI). It is the
+ * canonical cross-record link used by every lexicon that references
+ * another record (e.g., social replies/reposts, trade receipts → offers,
+ * trade.status → receipt, trade.receipt.linkedPost → social.post).
+ *
+ * Lives in the framework — not in any extension — so domain content
+ * doesn't have to re-invent the shape.
+ */
+
+export interface RecordRef {
+  readonly cid: CID;
+  readonly uri: string;
+}
+
+export const AT_URI_PATTERN = /^at:\/\/did:kash:[1-9A-HJ-NP-Za-km-z]{32,48}\/[a-z0-9.-]+\/[A-Za-z0-9_-]+$/;
+
+export const RECORD_REF_SCHEMA: ObjectSchema = S.object(
+  {
+    cid: S.string({ format: "cid" }),
+    uri: S.string({ pattern: AT_URI_PATTERN }),
+  },
+  ["cid", "uri"],
+);

package/src/extensions/social.ts

@@ -0,0 +1,179 @@
+/**
+ * Social Extension — domain lexicons (Indusland-shaped but Indusland-agnostic).
+ *
+ *   kash.social.post@1.0.0          — a post (text, media, optional Bento metadata).
+ *   kash.social.interaction@1.0.0   — unified like / share / react event.
+ *   kash.social.follow@1.0.0        — directed relationship between two DIDs.
+ *
+ * Import path: `@kashscript/lexicons/extensions/social`.
+ *
+ * This file is an **extension**: the Foundry core never auto-loads it.
+ * Consumers explicitly register `SOCIAL_EXTENSION` against their
+ * `LexiconRegistry` to opt in to social-domain validation.
+ *
+ * Data minimisation: every field that is not load-bearing for the specific
+ * action is optional.
+ */
+
+import { RECORD_REF_SCHEMA, type RecordRef } from "../envelope";
+import type { LexiconDef } from "../registry";
+import { S, type ObjectSchema } from "../schema";
+
+/* ─────────────────────────────────────────────────────────────────
+ *  kash.social.post@1.0.0
+ * ───────────────────────────────────────────────────────────────── */
+
+export const KASH_SOCIAL_POST_NSID    = "kash.social.post" as const;
+export const KASH_SOCIAL_POST_VERSION = { major: 1, minor: 0, patch: 0 } as const;
+export const KASH_SOCIAL_POST_ID      = "kash.social.post@1.0.0" as const;
+
+export type BentoAccent = "sun" | "poppy" | "sky" | "lilac" | "sage" | "rose";
+export type BentoSize   = "small" | "medium" | "large";
+
+export interface BentoMeta {
+  readonly title?: string;
+  readonly accent?: BentoAccent;
+  readonly size?: BentoSize;
+}
+
+export type PostMediaMime =
+  | "image/jpeg" | "image/png" | "image/webp" | "image/avif"
+  | "video/mp4"  | "video/webm"
+  | "audio/mpeg" | "audio/ogg";
+
+export interface PostMediaRef {
+  readonly cid: string;
+  readonly mimeType: PostMediaMime;
+  readonly altText?: string;
+  readonly width?: number;
+  readonly height?: number;
+  readonly durationMs?: number;
+}
+
+export interface KashSocialPostBody {
+  readonly text?: string;
+  readonly media?: readonly PostMediaRef[];
+  readonly bento?: BentoMeta;
+  readonly replyTo?: RecordRef;
+  readonly repostOf?: RecordRef;
+  readonly mentions?: readonly string[];
+  readonly tags?: readonly string[];
+  readonly lang?: string;
+}
+
+const POST_MEDIA_REF: ObjectSchema = S.object(
+  {
+    cid:        S.string({ format: "cid" }),
+    mimeType:   S.enum(
+      "image/jpeg", "image/png", "image/webp", "image/avif",
+      "video/mp4",  "video/webm",
+      "audio/mpeg", "audio/ogg",
+    ),
+    altText:    S.optional(S.string({ maxLength: 420 })),
+    width:      S.optional(S.number({ integer: true, min: 1, max: 16384 })),
+    height:     S.optional(S.number({ integer: true, min: 1, max: 16384 })),
+    durationMs: S.optional(S.number({ integer: true, min: 0, max: 86_400_000 })),
+  },
+  ["cid", "mimeType"],
+);
+
+const BENTO_META: ObjectSchema = S.object(
+  {
+    title:  S.optional(S.string({ minLength: 1, maxLength: 80 })),
+    accent: S.optional(S.enum("sun", "poppy", "sky", "lilac", "sage", "rose")),
+    size:   S.optional(S.enum("small", "medium", "large")),
+  },
+  [],
+);
+
+export const KASH_SOCIAL_POST_BODY_SCHEMA: ObjectSchema = S.object(
+  {
+    text:     S.optional(S.string({ maxLength: 1000 })),
+    media:    S.optional(S.array(POST_MEDIA_REF, { maxItems: 8 })),
+    bento:    S.optional(BENTO_META),
+    replyTo:  S.optional(RECORD_REF_SCHEMA),
+    repostOf: S.optional(RECORD_REF_SCHEMA),
+    mentions: S.optional(S.array(S.string({ format: "did-ks" }), { maxItems: 16 })),
+    tags:     S.optional(S.array(S.string({ minLength: 1, maxLength: 32, pattern: /^[a-z0-9][a-z0-9_-]*$/ }), { maxItems: 16 })),
+    lang:     S.optional(S.string({ format: "bcp47" })),
+  },
+  [],
+);
+
+/* ─────────────────────────────────────────────────────────────────
+ *  kash.social.interaction@1.0.0
+ * ───────────────────────────────────────────────────────────────── */
+
+export const KASH_SOCIAL_INTERACTION_NSID    = "kash.social.interaction" as const;
+export const KASH_SOCIAL_INTERACTION_VERSION = { major: 1, minor: 0, patch: 0 } as const;
+export const KASH_SOCIAL_INTERACTION_ID      = "kash.social.interaction@1.0.0" as const;
+
+export type InteractionType = "like" | "share" | "react";
+
+export interface KashSocialInteractionBody {
+  readonly type: InteractionType;
+  readonly target: RecordRef;
+  readonly reaction?: string;
+}
+
+export const KASH_SOCIAL_INTERACTION_BODY_SCHEMA: ObjectSchema = S.object(
+  {
+    type:     S.enum("like", "share", "react"),
+    target:   RECORD_REF_SCHEMA,
+    reaction: S.optional(S.string({ minLength: 1, maxLength: 16 })),
+  },
+  ["type", "target"],
+);
+
+/* ─────────────────────────────────────────────────────────────────
+ *  kash.social.follow@1.0.0
+ * ───────────────────────────────────────────────────────────────── */
+
+export const KASH_SOCIAL_FOLLOW_NSID    = "kash.social.follow" as const;
+export const KASH_SOCIAL_FOLLOW_VERSION = { major: 1, minor: 0, patch: 0 } as const;
+export const KASH_SOCIAL_FOLLOW_ID      = "kash.social.follow@1.0.0" as const;
+
+export interface KashSocialFollowBody {
+  readonly subject: string;
+  readonly subjectHandle?: string;
+}
+
+export const KASH_SOCIAL_FOLLOW_BODY_SCHEMA: ObjectSchema = S.object(
+  {
+    subject:       S.string({ format: "did-ks" }),
+    subjectHandle: S.optional(S.string({ minLength: 1, maxLength: 64 })),
+  },
+  ["subject"],
+);
+
+/* ─────────────────────────────────────────────────────────────────
+ *  Extension bundle
+ * ───────────────────────────────────────────────────────────────── */
+
+/** All Social-domain lexicons. Pass to `LexiconRegistry.registerAll()`. */
+export const SOCIAL_EXTENSION: readonly LexiconDef[] = [
+  {
+    id: KASH_SOCIAL_POST_ID,
+    nsid: KASH_SOCIAL_POST_NSID,
+    semver: KASH_SOCIAL_POST_VERSION,
+    bodySchema: KASH_SOCIAL_POST_BODY_SCHEMA,
+    title: "Social Post",
+    description: "A post — text, media, and optional Bento-style tile metadata.",
+  },
+  {
+    id: KASH_SOCIAL_INTERACTION_ID,
+    nsid: KASH_SOCIAL_INTERACTION_NSID,
+    semver: KASH_SOCIAL_INTERACTION_VERSION,
+    bodySchema: KASH_SOCIAL_INTERACTION_BODY_SCHEMA,
+    title: "Social Interaction",
+    description: "Unified like / share / react event against a post.",
+  },
+  {
+    id: KASH_SOCIAL_FOLLOW_ID,
+    nsid: KASH_SOCIAL_FOLLOW_NSID,
+    semver: KASH_SOCIAL_FOLLOW_VERSION,
+    bodySchema: KASH_SOCIAL_FOLLOW_BODY_SCHEMA,
+    title: "Social Follow",
+    description: "Directed follow relationship between two DIDs.",
+  },
+];