@daena/core 0.1.0-alpha.0

package/README.md

@@ -0,0 +1,17 @@
+# @daena/core
+
+Core types, schema validation, and document utilities for the Daena Protocol.
+
+This package is the foundation every other reference package depends on. It contains:
+
+- TypeScript types for Daena documents, facts, capabilities, and render hints
+- JSON Schema validators for the on-the-wire shapes defined in [SPEC.md](https://github.com/daena-protocol/spec/blob/main/SPEC.md)
+- Canonical serialization helpers required for stable signing
+
+## Status
+
+Pre-alpha. Interfaces will change as the spec evolves toward v1.
+
+## License
+
+[Apache-2.0](../../LICENSE).

package/dist/index.d.ts

@@ -0,0 +1,527 @@
+import { z, ZodError } from 'zod';
+
+/**
+ * Daena Protocol v0 — TypeScript types
+ *
+ * Derived from SPEC.md sections 2-5. These types track the editor's draft
+ * and will evolve until v1.0.
+ */
+/** A cryptographic attestation by a publisher. */
+interface Signature {
+    /** Algorithm identifier, e.g. "ed25519". */
+    algorithm: string;
+    /** Base64-encoded signature value. */
+    value: string;
+    /** DID URL identifying the key that produced the signature. */
+    keyId: string;
+}
+/** A typed, dated, signed statement made by a publisher about a subject. */
+interface Fact {
+    /** Stable identifier for this fact within the document. */
+    id: string;
+    /** URI identifying the vocabulary under which this fact is interpreted. */
+    type: string;
+    /** The fact's value. May be a primitive, object, or array. */
+    value: unknown;
+    /** ISO 8601 timestamp of when the fact was last asserted. */
+    asOf: string;
+    /** Optional per-fact signature. If absent, the document-level signature attests this fact. */
+    signature?: Signature;
+}
+/** Typed parameter specification for a capability. */
+interface CapabilityParameter {
+    type: "string" | "integer" | "number" | "boolean" | "datetime" | "phone" | "email";
+    required: boolean;
+    min?: number;
+    max?: number;
+    pattern?: string;
+}
+/** An action a publisher offers to agents. */
+interface Capability {
+    /** Stable identifier for this capability within the document. */
+    id: string;
+    /** Human-readable label for the action. */
+    name: string;
+    /** URI identifying the capability vocabulary. */
+    type: string;
+    /** Typed parameter specifications keyed by parameter name. */
+    parameters: Record<string, CapabilityParameter>;
+    /** HTTPS endpoint where ACT requests are sent. */
+    endpoint: string;
+    /** Authentication mode required to invoke this capability. */
+    auth: "none" | "bearer" | "did";
+    /** Optional payment requirement. */
+    price?: {
+        amount: number;
+        currency: string;
+    };
+}
+/** Optional metadata that guides how a renderer produces a human view. */
+interface RenderHints {
+    /** Title shown at the top of the rendered view. */
+    title?: string;
+    /** Ordered list of fact IDs to feature prominently. */
+    primary?: string[];
+    /** Ordered list of capability IDs to surface as primary actions. */
+    callsToAction?: string[];
+    /** Optional theming. */
+    theme?: {
+        accent?: string;
+    };
+}
+/** A complete Daena document — the atomic unit of publication. */
+interface DaenaDocument {
+    /** Protocol version. */
+    daena: "0";
+    /** Publisher identity as a Decentralized Identifier. */
+    publisher: string;
+    /** Signed statements made by the publisher. */
+    facts: Fact[];
+    /** Actions the publisher offers to agents. */
+    capabilities: Capability[];
+    /** Optional rendering metadata. */
+    render?: RenderHints;
+    /** Document-level signature. */
+    signature: Signature;
+}
+
+declare const SignatureSchema: z.ZodObject<{
+    algorithm: z.ZodString;
+    value: z.ZodString;
+    keyId: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    algorithm: string;
+    value: string;
+    keyId: string;
+}, {
+    algorithm: string;
+    value: string;
+    keyId: string;
+}>;
+declare const CapabilityParameterSchema: z.ZodObject<{
+    type: z.ZodEnum<["string", "integer", "number", "boolean", "datetime", "phone", "email"]>;
+    required: z.ZodBoolean;
+    min: z.ZodOptional<z.ZodNumber>;
+    max: z.ZodOptional<z.ZodNumber>;
+    pattern: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    type: "string" | "number" | "boolean" | "integer" | "datetime" | "phone" | "email";
+    required: boolean;
+    min?: number | undefined;
+    max?: number | undefined;
+    pattern?: string | undefined;
+}, {
+    type: "string" | "number" | "boolean" | "integer" | "datetime" | "phone" | "email";
+    required: boolean;
+    min?: number | undefined;
+    max?: number | undefined;
+    pattern?: string | undefined;
+}>;
+declare const CapabilitySchema: z.ZodObject<{
+    id: z.ZodString;
+    name: z.ZodString;
+    type: z.ZodString;
+    parameters: z.ZodRecord<z.ZodString, z.ZodObject<{
+        type: z.ZodEnum<["string", "integer", "number", "boolean", "datetime", "phone", "email"]>;
+        required: z.ZodBoolean;
+        min: z.ZodOptional<z.ZodNumber>;
+        max: z.ZodOptional<z.ZodNumber>;
+        pattern: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        type: "string" | "number" | "boolean" | "integer" | "datetime" | "phone" | "email";
+        required: boolean;
+        min?: number | undefined;
+        max?: number | undefined;
+        pattern?: string | undefined;
+    }, {
+        type: "string" | "number" | "boolean" | "integer" | "datetime" | "phone" | "email";
+        required: boolean;
+        min?: number | undefined;
+        max?: number | undefined;
+        pattern?: string | undefined;
+    }>>;
+    endpoint: z.ZodString;
+    auth: z.ZodEnum<["none", "bearer", "did"]>;
+    price: z.ZodOptional<z.ZodObject<{
+        amount: z.ZodNumber;
+        currency: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        amount: number;
+        currency: string;
+    }, {
+        amount: number;
+        currency: string;
+    }>>;
+}, "strip", z.ZodTypeAny, {
+    type: string;
+    id: string;
+    name: string;
+    parameters: Record<string, {
+        type: "string" | "number" | "boolean" | "integer" | "datetime" | "phone" | "email";
+        required: boolean;
+        min?: number | undefined;
+        max?: number | undefined;
+        pattern?: string | undefined;
+    }>;
+    endpoint: string;
+    auth: "none" | "bearer" | "did";
+    price?: {
+        amount: number;
+        currency: string;
+    } | undefined;
+}, {
+    type: string;
+    id: string;
+    name: string;
+    parameters: Record<string, {
+        type: "string" | "number" | "boolean" | "integer" | "datetime" | "phone" | "email";
+        required: boolean;
+        min?: number | undefined;
+        max?: number | undefined;
+        pattern?: string | undefined;
+    }>;
+    endpoint: string;
+    auth: "none" | "bearer" | "did";
+    price?: {
+        amount: number;
+        currency: string;
+    } | undefined;
+}>;
+declare const FactSchema: z.ZodObject<{
+    id: z.ZodString;
+    type: z.ZodString;
+    value: z.ZodUnknown;
+    asOf: z.ZodString;
+    signature: z.ZodOptional<z.ZodObject<{
+        algorithm: z.ZodString;
+        value: z.ZodString;
+        keyId: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        algorithm: string;
+        value: string;
+        keyId: string;
+    }, {
+        algorithm: string;
+        value: string;
+        keyId: string;
+    }>>;
+}, "strip", z.ZodTypeAny, {
+    type: string;
+    id: string;
+    asOf: string;
+    value?: unknown;
+    signature?: {
+        algorithm: string;
+        value: string;
+        keyId: string;
+    } | undefined;
+}, {
+    type: string;
+    id: string;
+    asOf: string;
+    value?: unknown;
+    signature?: {
+        algorithm: string;
+        value: string;
+        keyId: string;
+    } | undefined;
+}>;
+declare const RenderHintsSchema: z.ZodObject<{
+    title: z.ZodOptional<z.ZodString>;
+    primary: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    callsToAction: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    theme: z.ZodOptional<z.ZodObject<{
+        accent: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        accent?: string | undefined;
+    }, {
+        accent?: string | undefined;
+    }>>;
+}, "strip", z.ZodTypeAny, {
+    title?: string | undefined;
+    primary?: string[] | undefined;
+    callsToAction?: string[] | undefined;
+    theme?: {
+        accent?: string | undefined;
+    } | undefined;
+}, {
+    title?: string | undefined;
+    primary?: string[] | undefined;
+    callsToAction?: string[] | undefined;
+    theme?: {
+        accent?: string | undefined;
+    } | undefined;
+}>;
+declare const DaenaDocumentSchema: z.ZodObject<{
+    daena: z.ZodLiteral<"0">;
+    publisher: z.ZodString;
+    facts: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        type: z.ZodString;
+        value: z.ZodUnknown;
+        asOf: z.ZodString;
+        signature: z.ZodOptional<z.ZodObject<{
+            algorithm: z.ZodString;
+            value: z.ZodString;
+            keyId: z.ZodString;
+        }, "strip", z.ZodTypeAny, {
+            algorithm: string;
+            value: string;
+            keyId: string;
+        }, {
+            algorithm: string;
+            value: string;
+            keyId: string;
+        }>>;
+    }, "strip", z.ZodTypeAny, {
+        type: string;
+        id: string;
+        asOf: string;
+        value?: unknown;
+        signature?: {
+            algorithm: string;
+            value: string;
+            keyId: string;
+        } | undefined;
+    }, {
+        type: string;
+        id: string;
+        asOf: string;
+        value?: unknown;
+        signature?: {
+            algorithm: string;
+            value: string;
+            keyId: string;
+        } | undefined;
+    }>, "many">;
+    capabilities: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        name: z.ZodString;
+        type: z.ZodString;
+        parameters: z.ZodRecord<z.ZodString, z.ZodObject<{
+            type: z.ZodEnum<["string", "integer", "number", "boolean", "datetime", "phone", "email"]>;
+            required: z.ZodBoolean;
+            min: z.ZodOptional<z.ZodNumber>;
+            max: z.ZodOptional<z.ZodNumber>;
+            pattern: z.ZodOptional<z.ZodString>;
+        }, "strip", z.ZodTypeAny, {
+            type: "string" | "number" | "boolean" | "integer" | "datetime" | "phone" | "email";
+            required: boolean;
+            min?: number | undefined;
+            max?: number | undefined;
+            pattern?: string | undefined;
+        }, {
+            type: "string" | "number" | "boolean" | "integer" | "datetime" | "phone" | "email";
+            required: boolean;
+            min?: number | undefined;
+            max?: number | undefined;
+            pattern?: string | undefined;
+        }>>;
+        endpoint: z.ZodString;
+        auth: z.ZodEnum<["none", "bearer", "did"]>;
+        price: z.ZodOptional<z.ZodObject<{
+            amount: z.ZodNumber;
+            currency: z.ZodString;
+        }, "strip", z.ZodTypeAny, {
+            amount: number;
+            currency: string;
+        }, {
+            amount: number;
+            currency: string;
+        }>>;
+    }, "strip", z.ZodTypeAny, {
+        type: string;
+        id: string;
+        name: string;
+        parameters: Record<string, {
+            type: "string" | "number" | "boolean" | "integer" | "datetime" | "phone" | "email";
+            required: boolean;
+            min?: number | undefined;
+            max?: number | undefined;
+            pattern?: string | undefined;
+        }>;
+        endpoint: string;
+        auth: "none" | "bearer" | "did";
+        price?: {
+            amount: number;
+            currency: string;
+        } | undefined;
+    }, {
+        type: string;
+        id: string;
+        name: string;
+        parameters: Record<string, {
+            type: "string" | "number" | "boolean" | "integer" | "datetime" | "phone" | "email";
+            required: boolean;
+            min?: number | undefined;
+            max?: number | undefined;
+            pattern?: string | undefined;
+        }>;
+        endpoint: string;
+        auth: "none" | "bearer" | "did";
+        price?: {
+            amount: number;
+            currency: string;
+        } | undefined;
+    }>, "many">;
+    render: z.ZodOptional<z.ZodObject<{
+        title: z.ZodOptional<z.ZodString>;
+        primary: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        callsToAction: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        theme: z.ZodOptional<z.ZodObject<{
+            accent: z.ZodOptional<z.ZodString>;
+        }, "strip", z.ZodTypeAny, {
+            accent?: string | undefined;
+        }, {
+            accent?: string | undefined;
+        }>>;
+    }, "strip", z.ZodTypeAny, {
+        title?: string | undefined;
+        primary?: string[] | undefined;
+        callsToAction?: string[] | undefined;
+        theme?: {
+            accent?: string | undefined;
+        } | undefined;
+    }, {
+        title?: string | undefined;
+        primary?: string[] | undefined;
+        callsToAction?: string[] | undefined;
+        theme?: {
+            accent?: string | undefined;
+        } | undefined;
+    }>>;
+    signature: z.ZodObject<{
+        algorithm: z.ZodString;
+        value: z.ZodString;
+        keyId: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        algorithm: string;
+        value: string;
+        keyId: string;
+    }, {
+        algorithm: string;
+        value: string;
+        keyId: string;
+    }>;
+}, "strip", z.ZodTypeAny, {
+    signature: {
+        algorithm: string;
+        value: string;
+        keyId: string;
+    };
+    daena: "0";
+    publisher: string;
+    facts: {
+        type: string;
+        id: string;
+        asOf: string;
+        value?: unknown;
+        signature?: {
+            algorithm: string;
+            value: string;
+            keyId: string;
+        } | undefined;
+    }[];
+    capabilities: {
+        type: string;
+        id: string;
+        name: string;
+        parameters: Record<string, {
+            type: "string" | "number" | "boolean" | "integer" | "datetime" | "phone" | "email";
+            required: boolean;
+            min?: number | undefined;
+            max?: number | undefined;
+            pattern?: string | undefined;
+        }>;
+        endpoint: string;
+        auth: "none" | "bearer" | "did";
+        price?: {
+            amount: number;
+            currency: string;
+        } | undefined;
+    }[];
+    render?: {
+        title?: string | undefined;
+        primary?: string[] | undefined;
+        callsToAction?: string[] | undefined;
+        theme?: {
+            accent?: string | undefined;
+        } | undefined;
+    } | undefined;
+}, {
+    signature: {
+        algorithm: string;
+        value: string;
+        keyId: string;
+    };
+    daena: "0";
+    publisher: string;
+    facts: {
+        type: string;
+        id: string;
+        asOf: string;
+        value?: unknown;
+        signature?: {
+            algorithm: string;
+            value: string;
+            keyId: string;
+        } | undefined;
+    }[];
+    capabilities: {
+        type: string;
+        id: string;
+        name: string;
+        parameters: Record<string, {
+            type: "string" | "number" | "boolean" | "integer" | "datetime" | "phone" | "email";
+            required: boolean;
+            min?: number | undefined;
+            max?: number | undefined;
+            pattern?: string | undefined;
+        }>;
+        endpoint: string;
+        auth: "none" | "bearer" | "did";
+        price?: {
+            amount: number;
+            currency: string;
+        } | undefined;
+    }[];
+    render?: {
+        title?: string | undefined;
+        primary?: string[] | undefined;
+        callsToAction?: string[] | undefined;
+        theme?: {
+            accent?: string | undefined;
+        } | undefined;
+    } | undefined;
+}>;
+
+interface DaenaIssue {
+    path: string;
+    message: string;
+}
+declare class DaenaParseError extends Error {
+    readonly issues: DaenaIssue[];
+    constructor(zodError: ZodError);
+}
+
+/**
+ * Parse and validate a Daena document.
+ *
+ * Accepts either a JSON string or an already-parsed value.
+ * Throws DaenaParseError if the input fails v0 schema validation.
+ */
+declare function parse(input: string | unknown): DaenaDocument;
+/**
+ * Non-throwing variant of parse(). Returns a result object so callers can
+ * branch without try/catch.
+ */
+type ParseResult = {
+    ok: true;
+    doc: DaenaDocument;
+} | {
+    ok: false;
+    error: DaenaParseError;
+};
+declare function tryParse(input: string | unknown): ParseResult;
+
+export { type Capability, type CapabilityParameter, CapabilityParameterSchema, CapabilitySchema, type DaenaDocument, DaenaDocumentSchema, type DaenaIssue, DaenaParseError, type Fact, FactSchema, type ParseResult, type RenderHints, RenderHintsSchema, type Signature, SignatureSchema, parse, tryParse };

package/dist/index.js

@@ -0,0 +1,102 @@
+// src/schema.ts
+import { z } from "zod";
+var SignatureSchema = z.object({
+  algorithm: z.string().min(1),
+  value: z.string().min(1),
+  keyId: z.string().min(1)
+});
+var CapabilityParameterSchema = z.object({
+  type: z.enum([
+    "string",
+    "integer",
+    "number",
+    "boolean",
+    "datetime",
+    "phone",
+    "email"
+  ]),
+  required: z.boolean(),
+  min: z.number().optional(),
+  max: z.number().optional(),
+  pattern: z.string().optional()
+});
+var CapabilitySchema = z.object({
+  id: z.string().min(1),
+  name: z.string().min(1),
+  type: z.string().url(),
+  parameters: z.record(CapabilityParameterSchema),
+  endpoint: z.string().url(),
+  auth: z.enum(["none", "bearer", "did"]),
+  price: z.object({
+    amount: z.number(),
+    currency: z.string().length(3)
+  }).optional()
+});
+var FactSchema = z.object({
+  id: z.string().min(1),
+  type: z.string().url(),
+  value: z.unknown(),
+  asOf: z.string().datetime(),
+  signature: SignatureSchema.optional()
+});
+var RenderHintsSchema = z.object({
+  title: z.string().optional(),
+  primary: z.array(z.string()).optional(),
+  callsToAction: z.array(z.string()).optional(),
+  theme: z.object({
+    accent: z.string().optional()
+  }).optional()
+});
+var DaenaDocumentSchema = z.object({
+  daena: z.literal("0"),
+  publisher: z.string().min(1),
+  facts: z.array(FactSchema),
+  capabilities: z.array(CapabilitySchema),
+  render: RenderHintsSchema.optional(),
+  signature: SignatureSchema
+});
+
+// src/errors.ts
+var DaenaParseError = class extends Error {
+  issues;
+  constructor(zodError) {
+    const issues = zodError.errors.map((e) => ({
+      path: e.path.join(".") || "(root)",
+      message: e.message
+    }));
+    const summary = issues.slice(0, 3).map((i) => `${i.path}: ${i.message}`).join("; ");
+    const tail = issues.length > 3 ? ` (+${issues.length - 3} more)` : "";
+    super(`Invalid Daena document \u2014 ${summary}${tail}`);
+    this.name = "DaenaParseError";
+    this.issues = issues;
+  }
+};
+
+// src/parse.ts
+function parse(input) {
+  const raw = typeof input === "string" ? JSON.parse(input) : input;
+  const result = DaenaDocumentSchema.safeParse(raw);
+  if (!result.success) {
+    throw new DaenaParseError(result.error);
+  }
+  return result.data;
+}
+function tryParse(input) {
+  try {
+    return { ok: true, doc: parse(input) };
+  } catch (e) {
+    if (e instanceof DaenaParseError) return { ok: false, error: e };
+    throw e;
+  }
+}
+export {
+  CapabilityParameterSchema,
+  CapabilitySchema,
+  DaenaDocumentSchema,
+  DaenaParseError,
+  FactSchema,
+  RenderHintsSchema,
+  SignatureSchema,
+  parse,
+  tryParse
+};

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@daena/core",
+  "version": "0.1.0-alpha.0",
+  "description": "Core types and validation for the Daena Protocol",
+  "license": "Apache-2.0",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": ["src", "dist"],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/daena-protocol/daena.git",
+    "directory": "packages/core"
+  },
+  "homepage": "https://daena-protocol.org",
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --dts --clean",
+    "test": "vitest run",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "zod": "^3.23.0"
+  }
+}

package/src/errors.ts

@@ -0,0 +1,25 @@
+import type { ZodError } from "zod";
+
+export interface DaenaIssue {
+  path: string;
+  message: string;
+}
+
+export class DaenaParseError extends Error {
+  readonly issues: DaenaIssue[];
+
+  constructor(zodError: ZodError) {
+    const issues: DaenaIssue[] = zodError.errors.map((e) => ({
+      path: e.path.join(".") || "(root)",
+      message: e.message
+    }));
+    const summary = issues
+      .slice(0, 3)
+      .map((i) => `${i.path}: ${i.message}`)
+      .join("; ");
+    const tail = issues.length > 3 ? ` (+${issues.length - 3} more)` : "";
+    super(`Invalid Daena document — ${summary}${tail}`);
+    this.name = "DaenaParseError";
+    this.issues = issues;
+  }
+}

package/src/index.ts

@@ -0,0 +1,4 @@
+export * from "./types.js";
+export * from "./schema.js";
+export * from "./parse.js";
+export * from "./errors.js";

package/src/parse.ts

@@ -0,0 +1,35 @@
+import { DaenaDocumentSchema } from "./schema.js";
+import { DaenaParseError } from "./errors.js";
+import type { DaenaDocument } from "./types.js";
+
+/**
+ * Parse and validate a Daena document.
+ *
+ * Accepts either a JSON string or an already-parsed value.
+ * Throws DaenaParseError if the input fails v0 schema validation.
+ */
+export function parse(input: string | unknown): DaenaDocument {
+  const raw = typeof input === "string" ? JSON.parse(input) : input;
+  const result = DaenaDocumentSchema.safeParse(raw);
+  if (!result.success) {
+    throw new DaenaParseError(result.error);
+  }
+  return result.data as DaenaDocument;
+}
+
+/**
+ * Non-throwing variant of parse(). Returns a result object so callers can
+ * branch without try/catch.
+ */
+export type ParseResult =
+  | { ok: true; doc: DaenaDocument }
+  | { ok: false; error: DaenaParseError };
+
+export function tryParse(input: string | unknown): ParseResult {
+  try {
+    return { ok: true, doc: parse(input) };
+  } catch (e) {
+    if (e instanceof DaenaParseError) return { ok: false, error: e };
+    throw e;
+  }
+}

package/src/schema.ts

@@ -0,0 +1,66 @@
+import { z } from "zod";
+
+export const SignatureSchema = z.object({
+  algorithm: z.string().min(1),
+  value: z.string().min(1),
+  keyId: z.string().min(1)
+});
+
+export const CapabilityParameterSchema = z.object({
+  type: z.enum([
+    "string",
+    "integer",
+    "number",
+    "boolean",
+    "datetime",
+    "phone",
+    "email"
+  ]),
+  required: z.boolean(),
+  min: z.number().optional(),
+  max: z.number().optional(),
+  pattern: z.string().optional()
+});
+
+export const CapabilitySchema = z.object({
+  id: z.string().min(1),
+  name: z.string().min(1),
+  type: z.string().url(),
+  parameters: z.record(CapabilityParameterSchema),
+  endpoint: z.string().url(),
+  auth: z.enum(["none", "bearer", "did"]),
+  price: z
+    .object({
+      amount: z.number(),
+      currency: z.string().length(3)
+    })
+    .optional()
+});
+
+export const FactSchema = z.object({
+  id: z.string().min(1),
+  type: z.string().url(),
+  value: z.unknown(),
+  asOf: z.string().datetime(),
+  signature: SignatureSchema.optional()
+});
+
+export const RenderHintsSchema = z.object({
+  title: z.string().optional(),
+  primary: z.array(z.string()).optional(),
+  callsToAction: z.array(z.string()).optional(),
+  theme: z
+    .object({
+      accent: z.string().optional()
+    })
+    .optional()
+});
+
+export const DaenaDocumentSchema = z.object({
+  daena: z.literal("0"),
+  publisher: z.string().min(1),
+  facts: z.array(FactSchema),
+  capabilities: z.array(CapabilitySchema),
+  render: RenderHintsSchema.optional(),
+  signature: SignatureSchema
+});

package/src/types.ts

@@ -0,0 +1,90 @@
+/**
+ * Daena Protocol v0 — TypeScript types
+ *
+ * Derived from SPEC.md sections 2-5. These types track the editor's draft
+ * and will evolve until v1.0.
+ */
+
+/** A cryptographic attestation by a publisher. */
+export interface Signature {
+  /** Algorithm identifier, e.g. "ed25519". */
+  algorithm: string;
+  /** Base64-encoded signature value. */
+  value: string;
+  /** DID URL identifying the key that produced the signature. */
+  keyId: string;
+}
+
+/** A typed, dated, signed statement made by a publisher about a subject. */
+export interface Fact {
+  /** Stable identifier for this fact within the document. */
+  id: string;
+  /** URI identifying the vocabulary under which this fact is interpreted. */
+  type: string;
+  /** The fact's value. May be a primitive, object, or array. */
+  value: unknown;
+  /** ISO 8601 timestamp of when the fact was last asserted. */
+  asOf: string;
+  /** Optional per-fact signature. If absent, the document-level signature attests this fact. */
+  signature?: Signature;
+}
+
+/** Typed parameter specification for a capability. */
+export interface CapabilityParameter {
+  type: "string" | "integer" | "number" | "boolean" | "datetime" | "phone" | "email";
+  required: boolean;
+  min?: number;
+  max?: number;
+  pattern?: string;
+}
+
+/** An action a publisher offers to agents. */
+export interface Capability {
+  /** Stable identifier for this capability within the document. */
+  id: string;
+  /** Human-readable label for the action. */
+  name: string;
+  /** URI identifying the capability vocabulary. */
+  type: string;
+  /** Typed parameter specifications keyed by parameter name. */
+  parameters: Record<string, CapabilityParameter>;
+  /** HTTPS endpoint where ACT requests are sent. */
+  endpoint: string;
+  /** Authentication mode required to invoke this capability. */
+  auth: "none" | "bearer" | "did";
+  /** Optional payment requirement. */
+  price?: {
+    amount: number;
+    currency: string;
+  };
+}
+
+/** Optional metadata that guides how a renderer produces a human view. */
+export interface RenderHints {
+  /** Title shown at the top of the rendered view. */
+  title?: string;
+  /** Ordered list of fact IDs to feature prominently. */
+  primary?: string[];
+  /** Ordered list of capability IDs to surface as primary actions. */
+  callsToAction?: string[];
+  /** Optional theming. */
+  theme?: {
+    accent?: string;
+  };
+}
+
+/** A complete Daena document — the atomic unit of publication. */
+export interface DaenaDocument {
+  /** Protocol version. */
+  daena: "0";
+  /** Publisher identity as a Decentralized Identifier. */
+  publisher: string;
+  /** Signed statements made by the publisher. */
+  facts: Fact[];
+  /** Actions the publisher offers to agents. */
+  capabilities: Capability[];
+  /** Optional rendering metadata. */
+  render?: RenderHints;
+  /** Document-level signature. */
+  signature: Signature;
+}