@peac/schema 0.9.18 → 0.10.0

package/dist/obligations.js

@@ -0,0 +1,337 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ObligationsExtensionSchema = exports.OBLIGATIONS_EXTENSION_KEY = exports.ContributionObligationSchema = exports.CreditObligationSchema = exports.CONTRIBUTION_TYPES = exports.ContributionTypeSchema = exports.CREDIT_METHODS = exports.CreditMethodSchema = void 0;
+exports.validateCreditObligation = validateCreditObligation;
+exports.validateContributionObligation = validateContributionObligation;
+exports.validateObligationsExtension = validateObligationsExtension;
+exports.extractObligationsExtension = extractObligationsExtension;
+exports.isCreditRequired = isCreditRequired;
+exports.isContributionRequired = isContributionRequired;
+exports.createCreditObligation = createCreditObligation;
+exports.createContributionObligation = createContributionObligation;
+exports.createObligationsExtension = createObligationsExtension;
+/**
+ * PEAC Obligations Extension Types (v0.9.26+)
+ *
+ * Defines credit and contribution obligations for receipts,
+ * aligned with Creative Commons Signals framework.
+ *
+ * The `peac/obligations` extension allows content owners to specify
+ * requirements for credit/attribution and contribution models.
+ *
+ * @see https://creativecommons.org/signals/ for CC Signals background
+ */
+const zod_1 = require("zod");
+// =============================================================================
+// CREDIT METHOD (v0.9.26+)
+// =============================================================================
+/**
+ * How credit/attribution should be provided.
+ *
+ * - 'inline': Credit appears inline with the generated content
+ * - 'references': Credit appears in a references/sources section
+ * - 'model-card': Credit appears in model documentation/card
+ */
+exports.CreditMethodSchema = zod_1.z.enum(['inline', 'references', 'model-card']);
+/**
+ * Array of valid credit methods for runtime checks.
+ */
+exports.CREDIT_METHODS = ['inline', 'references', 'model-card'];
+// =============================================================================
+// CONTRIBUTION TYPE (v0.9.26+)
+// =============================================================================
+/**
+ * Type of contribution model.
+ *
+ * - 'direct': Direct payment to content owner
+ * - 'ecosystem': Contribution to ecosystem fund/coalition
+ * - 'open': Freely usable (no payment required)
+ */
+exports.ContributionTypeSchema = zod_1.z.enum(['direct', 'ecosystem', 'open']);
+/**
+ * Array of valid contribution types for runtime checks.
+ */
+exports.CONTRIBUTION_TYPES = ['direct', 'ecosystem', 'open'];
+// =============================================================================
+// CREDIT OBLIGATION (v0.9.26+)
+// =============================================================================
+/**
+ * CreditObligation - specifies attribution/credit requirements.
+ *
+ * Content owners can require credit when their content is used,
+ * specifying where and how the credit should appear.
+ *
+ * @example
+ * ```typescript
+ * const credit: CreditObligation = {
+ *   required: true,
+ *   citation_url: 'https://publisher.example/collection',
+ *   method: 'references',
+ * };
+ * ```
+ */
+exports.CreditObligationSchema = zod_1.z
+    .object({
+    /** Whether credit is required (REQUIRED) */
+    required: zod_1.z.boolean(),
+    /** URL for citation/attribution (OPTIONAL) */
+    citation_url: zod_1.z.string().url().max(2048).optional(),
+    /** How credit should be provided (OPTIONAL, defaults to implementation choice) */
+    method: exports.CreditMethodSchema.optional(),
+    /** Human-readable credit text template (OPTIONAL) */
+    credit_text: zod_1.z.string().max(1024).optional(),
+})
+    .strict()
+    .superRefine((data, ctx) => {
+    // If credit is required, at least one of citation_url, credit_text, or method must be specified
+    if (data.required && !data.citation_url && !data.credit_text && !data.method) {
+        ctx.addIssue({
+            code: zod_1.z.ZodIssueCode.custom,
+            message: 'When credit is required, at least one of citation_url, credit_text, or method must be specified',
+            path: ['required'],
+        });
+    }
+});
+// =============================================================================
+// CONTRIBUTION OBLIGATION (v0.9.26+)
+// =============================================================================
+/**
+ * ContributionObligation - specifies contribution/payment model.
+ *
+ * Aligned with CC Signals reciprocity framework:
+ * - direct: Payment goes directly to content owner
+ * - ecosystem: Payment goes to shared ecosystem fund
+ * - open: Content is freely usable
+ *
+ * @example
+ * ```typescript
+ * const contribution: ContributionObligation = {
+ *   type: 'ecosystem',
+ *   destination: 'https://fund.creativecommons.org',
+ * };
+ * ```
+ */
+exports.ContributionObligationSchema = zod_1.z
+    .object({
+    /** Type of contribution (REQUIRED) */
+    type: exports.ContributionTypeSchema,
+    /** Destination for contributions (OPTIONAL, e.g., fund URL, wallet address) */
+    destination: zod_1.z.string().max(2048).optional(),
+    /** Minimum contribution amount in minor units (OPTIONAL) */
+    min_amount: zod_1.z.number().int().min(0).optional(),
+    /** Currency for min_amount (OPTIONAL, ISO 4217 or crypto symbol like USDC) */
+    currency: zod_1.z
+        .string()
+        .min(3)
+        .max(8)
+        .regex(/^[A-Z0-9]{3,8}$/)
+        .optional(),
+})
+    .strict()
+    .superRefine((data, ctx) => {
+    // If type is 'direct' or 'ecosystem', destination is required
+    if ((data.type === 'direct' || data.type === 'ecosystem') && !data.destination) {
+        ctx.addIssue({
+            code: zod_1.z.ZodIssueCode.custom,
+            message: `Destination is required when contribution type is '${data.type}'`,
+            path: ['destination'],
+        });
+    }
+    // min_amount requires currency
+    if (data.min_amount !== undefined && !data.currency) {
+        ctx.addIssue({
+            code: zod_1.z.ZodIssueCode.custom,
+            message: 'Currency is required when min_amount is specified',
+            path: ['currency'],
+        });
+    }
+});
+// =============================================================================
+// OBLIGATIONS EXTENSION (v0.9.26+)
+// =============================================================================
+/**
+ * Extension key for obligations
+ */
+exports.OBLIGATIONS_EXTENSION_KEY = 'peac/obligations';
+/**
+ * ObligationsExtension - the full obligations extension block.
+ *
+ * This extension is added to receipt extensions under the key `peac/obligations`.
+ *
+ * @example
+ * ```typescript
+ * const receipt = {
+ *   // ... receipt fields ...
+ *   extensions: {
+ *     'peac/obligations': {
+ *       credit: {
+ *         required: true,
+ *         citation_url: 'https://publisher.example/collection',
+ *         method: 'references',
+ *       },
+ *       contribution: {
+ *         type: 'ecosystem',
+ *         destination: 'https://fund.example.org',
+ *       },
+ *     },
+ *   },
+ * };
+ * ```
+ */
+exports.ObligationsExtensionSchema = zod_1.z
+    .object({
+    /** Credit/attribution obligations (OPTIONAL) */
+    credit: exports.CreditObligationSchema.optional(),
+    /** Contribution/payment model (OPTIONAL) */
+    contribution: exports.ContributionObligationSchema.optional(),
+})
+    .strict();
+// =============================================================================
+// VALIDATION HELPERS (v0.9.26+)
+// =============================================================================
+/**
+ * Validate a CreditObligation.
+ *
+ * @param data - Unknown data to validate
+ * @returns Result with validated obligation or error message
+ */
+function validateCreditObligation(data) {
+    const result = exports.CreditObligationSchema.safeParse(data);
+    if (result.success) {
+        return { ok: true, value: result.data };
+    }
+    return { ok: false, error: result.error.message };
+}
+/**
+ * Validate a ContributionObligation.
+ *
+ * @param data - Unknown data to validate
+ * @returns Result with validated obligation or error message
+ */
+function validateContributionObligation(data) {
+    const result = exports.ContributionObligationSchema.safeParse(data);
+    if (result.success) {
+        return { ok: true, value: result.data };
+    }
+    return { ok: false, error: result.error.message };
+}
+/**
+ * Validate an ObligationsExtension.
+ *
+ * @param data - Unknown data to validate
+ * @returns Result with validated extension or error message
+ *
+ * @example
+ * ```typescript
+ * const result = validateObligationsExtension(data);
+ * if (result.ok) {
+ *   if (result.value.credit?.required) {
+ *     console.log('Credit required:', result.value.credit.citation_url);
+ *   }
+ * }
+ * ```
+ */
+function validateObligationsExtension(data) {
+    const result = exports.ObligationsExtensionSchema.safeParse(data);
+    if (result.success) {
+        return { ok: true, value: result.data };
+    }
+    return { ok: false, error: result.error.message };
+}
+/**
+ * Extract obligations extension from a receipt's extensions object.
+ *
+ * @param extensions - Extensions object from receipt
+ * @returns Validated obligations or undefined if not present
+ */
+function extractObligationsExtension(extensions) {
+    if (!extensions || !(exports.OBLIGATIONS_EXTENSION_KEY in extensions)) {
+        return undefined;
+    }
+    const result = validateObligationsExtension(extensions[exports.OBLIGATIONS_EXTENSION_KEY]);
+    if (result.ok) {
+        return result.value;
+    }
+    return undefined;
+}
+/**
+ * Check if credit is required based on obligations.
+ *
+ * @param obligations - Obligations extension
+ * @returns True if credit is explicitly required
+ */
+function isCreditRequired(obligations) {
+    return obligations?.credit?.required === true;
+}
+/**
+ * Check if contribution is required (non-open type).
+ *
+ * @param obligations - Obligations extension
+ * @returns True if contribution type is 'direct' or 'ecosystem'
+ */
+function isContributionRequired(obligations) {
+    const type = obligations?.contribution?.type;
+    return type === 'direct' || type === 'ecosystem';
+}
+/**
+ * Create a credit-only obligations extension.
+ *
+ * @param params - Credit parameters
+ * @returns ObligationsExtension with credit only
+ */
+function createCreditObligation(params) {
+    const credit = { required: params.required };
+    if (params.citation_url)
+        credit.citation_url = params.citation_url;
+    if (params.method)
+        credit.method = params.method;
+    if (params.credit_text)
+        credit.credit_text = params.credit_text;
+    return { credit };
+}
+/**
+ * Create a contribution-only obligations extension.
+ *
+ * @param params - Contribution parameters
+ * @returns ObligationsExtension with contribution only
+ */
+function createContributionObligation(params) {
+    const contribution = { type: params.type };
+    if (params.destination)
+        contribution.destination = params.destination;
+    if (params.min_amount !== undefined)
+        contribution.min_amount = params.min_amount;
+    if (params.currency)
+        contribution.currency = params.currency;
+    return { contribution };
+}
+/**
+ * Create a full obligations extension with both credit and contribution.
+ *
+ * @param credit - Credit obligation parameters
+ * @param contribution - Contribution obligation parameters
+ * @returns Full ObligationsExtension
+ */
+function createObligationsExtension(credit, contribution) {
+    const result = {};
+    if (credit) {
+        result.credit = { required: credit.required };
+        if (credit.citation_url)
+            result.credit.citation_url = credit.citation_url;
+        if (credit.method)
+            result.credit.method = credit.method;
+        if (credit.credit_text)
+            result.credit.credit_text = credit.credit_text;
+    }
+    if (contribution) {
+        result.contribution = { type: contribution.type };
+        if (contribution.destination)
+            result.contribution.destination = contribution.destination;
+        if (contribution.min_amount !== undefined)
+            result.contribution.min_amount = contribution.min_amount;
+        if (contribution.currency)
+            result.contribution.currency = contribution.currency;
+    }
+    return result;
+}
+//# sourceMappingURL=obligations.js.map

package/dist/obligations.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"obligations.js","sourceRoot":"","sources":["../src/obligations.ts"],"names":[],"mappings":"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"}

package/dist/purpose.d.ts

@@ -0,0 +1,272 @@
+/**
+ * PEAC Purpose Types (v0.9.24+)
+ *
+ * Purpose type hierarchy for forward-compatible purpose handling:
+ * - PurposeToken: Wire format (string) - preserves unknown tokens
+ * - CanonicalPurpose: PEAC's normative vocabulary - enforcement semantics
+ * - PurposeReason: Audit spine for enforcement decisions
+ *
+ * @see specs/kernel/constants.json for canonical values
+ */
+/**
+ * PurposeToken - Wire format string with validation grammar
+ *
+ * Allows unknown tokens for forward compatibility. Any valid token
+ * that matches the grammar is accepted and preserved.
+ *
+ * Grammar: lowercase, max 64 chars, [a-z0-9_-] + optional vendor prefix (vendor:token)
+ * Hyphens allowed for interop with external systems (Cloudflare, IETF AIPREF, etc.)
+ *
+ * Examples: "train", "search", "user_action", "user-action", "cf:ai_crawler", "cf:ai-crawler"
+ */
+export type PurposeToken = string;
+/**
+ * CanonicalPurpose - PEAC's normative vocabulary
+ *
+ * These are the only tokens PEAC enforces semantics for.
+ * Matches specs/kernel/constants.json purpose.canonical_tokens.
+ *
+ * - train: Model training data collection
+ * - search: Traditional search indexing
+ * - user_action: Agent acting on user behalf (v0.9.24+)
+ * - inference: Runtime inference / RAG
+ * - index: Content indexing (store)
+ */
+export type CanonicalPurpose = 'train' | 'search' | 'user_action' | 'inference' | 'index';
+/**
+ * Internal-only purpose value (never valid on wire)
+ *
+ * Applied when PEAC-Purpose header is missing or empty.
+ * Explicit "undeclared" in request -> 400 Bad Request.
+ */
+export type InternalPurpose = 'undeclared';
+/**
+ * PurposeReason - Audit spine for enforcement decisions
+ *
+ * Captures WHY a purpose was enforced differently than declared.
+ * Matches specs/kernel/constants.json purpose.reason_values.
+ */
+export type PurposeReason = 'allowed' | 'constrained' | 'denied' | 'downgraded' | 'undeclared_default' | 'unknown_preserved';
+/**
+ * Legacy purpose tokens from pre-v0.9.24
+ *
+ * These are mapped to CanonicalPurpose via mapLegacyToCanonical().
+ * Retained for backward compatibility with existing ControlPurpose usage.
+ */
+export type LegacyPurpose = 'crawl' | 'ai_input' | 'ai_index';
+/**
+ * Grammar validation for PurposeToken
+ *
+ * Pattern: lowercase letter, optionally followed by alphanumeric/underscore/hyphen
+ * characters that MUST end with a letter or digit (no trailing separators).
+ * Optional vendor prefix separated by colon follows the same rules.
+ *
+ * Hyphens are allowed for interoperability with external systems (Cloudflare,
+ * IETF AIPREF, etc.) that use hyphenated tokens like "user-action" or "train-ai".
+ *
+ * Valid: "train", "user_action", "user-action", "cf:ai_crawler", "cf:ai-crawler", "a", "a1"
+ * Invalid: "Train", "123abc", "", "-train", "train-", "train_", "cf:ai-", "cf:-ai"
+ */
+export declare const PURPOSE_TOKEN_REGEX: RegExp;
+/** Maximum length for a purpose token */
+export declare const MAX_PURPOSE_TOKEN_LENGTH = 64;
+/** Maximum number of purpose tokens per request (RECOMMENDED, not MUST) */
+export declare const MAX_PURPOSE_TOKENS_PER_REQUEST = 10;
+/** Canonical purpose tokens (from constants.json) */
+export declare const CANONICAL_PURPOSES: readonly CanonicalPurpose[];
+/** Purpose reason values (from constants.json) */
+export declare const PURPOSE_REASONS: readonly PurposeReason[];
+/** Internal-only purpose value */
+export declare const INTERNAL_PURPOSE_UNDECLARED: InternalPurpose;
+/**
+ * Check if a string is a valid PurposeToken
+ *
+ * Validates against the purpose token grammar:
+ * - Lowercase letters, digits, underscores, hyphens
+ * - Optional vendor prefix with colon
+ * - Max 64 characters
+ * - Must start with lowercase letter
+ *
+ * @param token - String to validate
+ * @returns true if valid PurposeToken
+ */
+export declare function isValidPurposeToken(token: string): token is PurposeToken;
+/**
+ * Check if a PurposeToken is a CanonicalPurpose
+ *
+ * @param token - Token to check
+ * @returns true if token is in canonical vocabulary
+ */
+export declare function isCanonicalPurpose(token: string): token is CanonicalPurpose;
+/**
+ * Check if a PurposeToken is a LegacyPurpose
+ *
+ * @param token - Token to check
+ * @returns true if token is a legacy purpose
+ */
+export declare function isLegacyPurpose(token: string): token is LegacyPurpose;
+/**
+ * Check if a string is a valid PurposeReason
+ *
+ * @param reason - String to check
+ * @returns true if valid PurposeReason
+ */
+export declare function isValidPurposeReason(reason: string): reason is PurposeReason;
+/**
+ * Check if a purpose token is the internal-only "undeclared" value
+ *
+ * Used to reject explicit "undeclared" on wire (400 Bad Request).
+ *
+ * @param token - Token to check
+ * @returns true if token is "undeclared"
+ */
+export declare function isUndeclaredPurpose(token: string): boolean;
+/**
+ * Normalize a purpose token
+ *
+ * Applies normalization rules:
+ * - Trim whitespace
+ * - Lowercase
+ *
+ * @param token - Raw token from header
+ * @returns Normalized token
+ */
+export declare function normalizePurposeToken(token: string): string;
+/**
+ * Parse PEAC-Purpose header value into array of tokens
+ *
+ * Applies parsing rules:
+ * - Split on commas
+ * - Trim optional whitespace (OWS) around tokens
+ * - Lowercase all tokens
+ * - Drop empty tokens
+ * - Deduplicate
+ * - Preserve input order
+ *
+ * @param headerValue - Raw PEAC-Purpose header value
+ * @returns Array of normalized PurposeToken values
+ */
+export declare function parsePurposeHeader(headerValue: string): PurposeToken[];
+/**
+ * Validate parsed purpose tokens
+ *
+ * Returns validation result with:
+ * - valid: All tokens pass grammar validation
+ * - tokens: All normalized tokens (including invalid ones)
+ * - invalidTokens: Tokens that failed grammar validation
+ * - undeclaredPresent: true if explicit "undeclared" was found (should reject)
+ *
+ * @param tokens - Array of parsed tokens
+ * @returns Validation result
+ */
+export interface PurposeValidationResult {
+    valid: boolean;
+    tokens: PurposeToken[];
+    invalidTokens: string[];
+    undeclaredPresent: boolean;
+}
+export declare function validatePurposeTokens(tokens: PurposeToken[]): PurposeValidationResult;
+/**
+ * Derive known canonical purposes from declared tokens
+ *
+ * Filters purpose_declared to get only canonical purposes.
+ * This is a helper derivation, NOT stored on wire.
+ *
+ * @param declared - Array of declared PurposeTokens
+ * @returns Array of CanonicalPurpose tokens
+ */
+export declare function deriveKnownPurposes(declared: PurposeToken[]): CanonicalPurpose[];
+/**
+ * Map legacy purpose to canonical purpose
+ *
+ * Used for backward compatibility with pre-v0.9.24 ControlPurpose values.
+ *
+ * @param legacy - Legacy purpose token
+ * @returns Mapping result with canonical purpose and audit note
+ */
+export interface LegacyMappingResult {
+    canonical: CanonicalPurpose;
+    mapping_note: string;
+}
+export declare function mapLegacyToCanonical(legacy: LegacyPurpose): LegacyMappingResult;
+/**
+ * Normalize any purpose token (canonical, legacy, or unknown)
+ *
+ * Returns the canonical form if known, otherwise preserves the token.
+ *
+ * @param token - Any valid PurposeToken
+ * @returns Canonical purpose if mapped, otherwise original token
+ */
+export declare function normalizeToCanonicalOrPreserve(token: PurposeToken): {
+    purpose: CanonicalPurpose;
+    mapped: false;
+} | {
+    purpose: PurposeToken;
+    mapped: true;
+    from: LegacyPurpose;
+} | {
+    purpose: PurposeToken;
+    mapped: false;
+    unknown: true;
+};
+/**
+ * Decision type for purpose reason determination
+ *
+ * Maps to policy decisions that affect purpose enforcement.
+ */
+export type PurposeDecision = 'allowed' | 'constrained' | 'denied' | 'downgraded';
+/**
+ * Context for determining purpose reason
+ */
+export interface PurposeReasonContext {
+    /**
+     * Whether purposes were declared (PEAC-Purpose header present and non-empty).
+     * If false, reason will be 'undeclared_default'.
+     */
+    declared: boolean;
+    /**
+     * Whether any unknown (non-canonical) tokens are present in declared purposes.
+     * If true and declared is true, reason will be 'unknown_preserved'.
+     */
+    hasUnknownTokens: boolean;
+    /**
+     * The policy decision (only used if declared and no unknown tokens).
+     * Defaults to 'allowed' if not provided.
+     */
+    decision?: PurposeDecision;
+}
+/**
+ * Determine the appropriate PurposeReason based on context
+ *
+ * This helper implements the decision logic for the audit spine:
+ * 1. If no purposes declared -> 'undeclared_default'
+ * 2. If unknown tokens present -> 'unknown_preserved'
+ * 3. Otherwise -> maps to policy decision
+ *
+ * @param context - Context for determination
+ * @returns The appropriate PurposeReason for the audit spine
+ *
+ * @example
+ * ```typescript
+ * // Missing PEAC-Purpose header
+ * determinePurposeReason({ declared: false, hasUnknownTokens: false });
+ * // => 'undeclared_default'
+ *
+ * // Has vendor-prefixed tokens
+ * determinePurposeReason({ declared: true, hasUnknownTokens: true, decision: 'allowed' });
+ * // => 'unknown_preserved'
+ *
+ * // All canonical tokens, allowed by policy
+ * determinePurposeReason({ declared: true, hasUnknownTokens: false, decision: 'allowed' });
+ * // => 'allowed'
+ * ```
+ */
+export declare function determinePurposeReason(context: PurposeReasonContext): PurposeReason;
+/**
+ * Check if any tokens in an array are unknown (non-canonical)
+ *
+ * @param tokens - Array of purpose tokens
+ * @returns true if any token is not a canonical purpose
+ */
+export declare function hasUnknownPurposeTokens(tokens: PurposeToken[]): boolean;
+//# sourceMappingURL=purpose.d.ts.map

package/dist/purpose.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"purpose.d.ts","sourceRoot":"","sources":["../src/purpose.ts"],"names":[],"mappings":"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"}