@contractspec/lib.contracts-spec 2.0.0

package/dist/ownership.d.ts

@@ -0,0 +1,211 @@
+/**
+ * Ownership, stability, and tagging types for ContractSpec.
+ *
+ * Provides canonical enums and metadata interfaces for spec ownership,
+ * lifecycle stages, and categorization.
+ *
+ * @module ownership
+ */
+import type { DocId } from './docs';
+/**
+ * Lifecycle stability stages for specs.
+ *
+ * Specs progress through these stages as they mature:
+ * - `idea`: Initial concept, not implemented
+ * - `in_creation`: Currently being built
+ * - `experimental`: Working but may change significantly
+ * - `beta`: Feature-complete, seeking feedback
+ * - `stable`: Production-ready, breaking changes require major version bump
+ * - `deprecated`: Scheduled for removal, use alternatives
+ */
+export declare const StabilityEnum: {
+    /** Initial concept, not yet implemented. */
+    readonly Idea: "idea";
+    /** Currently being built, not ready for use. */
+    readonly InCreation: "in_creation";
+    /** Working but unstable, may change significantly. */
+    readonly Experimental: "experimental";
+    /** Feature-complete, seeking feedback before stabilization. */
+    readonly Beta: "beta";
+    /** Production-ready, follows semantic versioning. */
+    readonly Stable: "stable";
+    /** Scheduled for removal, use alternatives. */
+    readonly Deprecated: "deprecated";
+};
+/** Stability level for a spec's lifecycle stage. */
+export type Stability = (typeof StabilityEnum)[keyof typeof StabilityEnum];
+/**
+ * Curated owner identifiers for business/product ownership.
+ *
+ * Used for CODEOWNERS, on-call routing, and approval workflows.
+ * Custom owner strings are also allowed for flexibility.
+ */
+export declare const OwnersEnum: {
+    /** Core platform team. */
+    readonly PlatformCore: "platform.core";
+    /** Sigil/auth team. */
+    readonly PlatformSigil: "platform.sigil";
+    /** Marketplace team. */
+    readonly PlatformMarketplace: "platform.marketplace";
+    /** Messaging/notifications team. */
+    readonly PlatformMessaging: "platform.messaging";
+    /** Content/CMS team. */
+    readonly PlatformContent: "platform.content";
+    /** Feature flags team. */
+    readonly PlatformFeatureFlags: "platform.featureflags";
+    /** Finance/billing team. */
+    readonly PlatformFinance: "platform.finance";
+};
+/**
+ * Owner identifier for a spec.
+ * Can be a predefined OwnersEnum value or any custom string.
+ */
+export type Owner = (typeof OwnersEnum)[keyof typeof OwnersEnum] | (string & {});
+/** @deprecated Use OwnersEnum instead. */
+export declare const Owners: {
+    /** Core platform team. */
+    readonly PlatformCore: "platform.core";
+    /** Sigil/auth team. */
+    readonly PlatformSigil: "platform.sigil";
+    /** Marketplace team. */
+    readonly PlatformMarketplace: "platform.marketplace";
+    /** Messaging/notifications team. */
+    readonly PlatformMessaging: "platform.messaging";
+    /** Content/CMS team. */
+    readonly PlatformContent: "platform.content";
+    /** Feature flags team. */
+    readonly PlatformFeatureFlags: "platform.featureflags";
+    /** Finance/billing team. */
+    readonly PlatformFinance: "platform.finance";
+};
+/**
+ * Common tags for categorizing specs.
+ *
+ * Used for search, grouping, and documentation navigation.
+ * Custom tag strings are also allowed for flexibility.
+ */
+export declare const TagsEnum: {
+    /** Spots/locations domain. */
+    readonly Spots: "spots";
+    /** Collectivity/community domain. */
+    readonly Collectivity: "collectivity";
+    /** Marketplace domain. */
+    readonly Marketplace: "marketplace";
+    /** Seller-related features. */
+    readonly Sellers: "sellers";
+    /** Authentication features. */
+    readonly Auth: "auth";
+    /** Login flows. */
+    readonly Login: "login";
+    /** Signup flows. */
+    readonly Signup: "signup";
+    /** Onboarding/guides. */
+    readonly Guide: "guide";
+    /** Documentation. */
+    readonly Docs: "docs";
+    /** Internationalization. */
+    readonly I18n: "i18n";
+    /** Incident management. */
+    readonly Incident: "incident";
+    /** Automation/workflows. */
+    readonly Automation: "automation";
+    /** Code hygiene/maintenance. */
+    readonly Hygiene: "hygiene";
+};
+/**
+ * Tag for categorizing a spec.
+ * Can be a predefined TagsEnum value or any custom string.
+ */
+export type Tag = (typeof TagsEnum)[keyof typeof TagsEnum] | (string & {});
+/** @deprecated Use TagsEnum instead. */
+export declare const Tags: {
+    /** Spots/locations domain. */
+    readonly Spots: "spots";
+    /** Collectivity/community domain. */
+    readonly Collectivity: "collectivity";
+    /** Marketplace domain. */
+    readonly Marketplace: "marketplace";
+    /** Seller-related features. */
+    readonly Sellers: "sellers";
+    /** Authentication features. */
+    readonly Auth: "auth";
+    /** Login flows. */
+    readonly Login: "login";
+    /** Signup flows. */
+    readonly Signup: "signup";
+    /** Onboarding/guides. */
+    readonly Guide: "guide";
+    /** Documentation. */
+    readonly Docs: "docs";
+    /** Internationalization. */
+    readonly I18n: "i18n";
+    /** Incident management. */
+    readonly Incident: "incident";
+    /** Automation/workflows. */
+    readonly Automation: "automation";
+    /** Code hygiene/maintenance. */
+    readonly Hygiene: "hygiene";
+};
+/**
+ * Common metadata interface for all ContractSpec specifications.
+ *
+ * Every spec type (operations, events, presentations, etc.) extends this
+ * interface to provide consistent ownership, versioning, and discoverability.
+ *
+ * @example
+ * ```typescript
+ * const meta: OwnerShipMeta = {
+ *   key: 'auth.login',
+ *   version: '1.0.0',
+ *   description: 'Authenticates a user with email and password',
+ *   stability: StabilityEnum.Stable,
+ *   owners: [OwnersEnum.PlatformSigil],
+ *   tags: [TagsEnum.Auth, TagsEnum.Login],
+ * };
+ * ```
+ */
+export interface OwnerShipMeta {
+    /**
+     * Semantic version string (e.g., "1.0.0").
+     * Bump for breaking changes according to semver rules.
+     */
+    version: string;
+    /**
+     * Fully-qualified spec key (e.g., "sigil.beginSignup", "user.created").
+     * Must be unique within the spec type.
+     */
+    key: string;
+    /**
+     * Human-friendly title (e.g., "Begin Signup").
+     * Used in documentation and UI.
+     */
+    title?: string;
+    /**
+     * Short human-friendly summary of what this spec does.
+     * Should be concise (1-2 sentences).
+     */
+    description: string;
+    /**
+     * Business domain this spec belongs to (e.g., "auth", "marketplace").
+     * Used for grouping and discovery.
+     */
+    domain?: string;
+    /**
+     * Lifecycle stability marker.
+     * Indicates maturity level and change expectations.
+     */
+    stability: Stability;
+    /**
+     * Team/individual owners responsible for this spec.
+     * Used for CODEOWNERS, on-call routing, and approvals.
+     */
+    owners: Owner[];
+    /**
+     * Tags for search, grouping, and documentation navigation.
+     */
+    tags: Tag[];
+    /**
+     * Associated DocBlock identifiers for documentation linkage.
+     */
+    docId?: DocId[];
+}

package/dist/ownership.js

@@ -0,0 +1,73 @@
+// @bun
+var __defProp = Object.defineProperty;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __moduleCache = /* @__PURE__ */ new WeakMap;
+var __toCommonJS = (from) => {
+  var entry = __moduleCache.get(from), desc;
+  if (entry)
+    return entry;
+  entry = __defProp({}, "__esModule", { value: true });
+  if (from && typeof from === "object" || typeof from === "function")
+    __getOwnPropNames(from).map((key) => !__hasOwnProp.call(entry, key) && __defProp(entry, key, {
+      get: () => from[key],
+      enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
+    }));
+  __moduleCache.set(from, entry);
+  return entry;
+};
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, {
+      get: all[name],
+      enumerable: true,
+      configurable: true,
+      set: (newValue) => all[name] = () => newValue
+    });
+};
+var __esm = (fn, res) => () => (fn && (res = fn(fn = 0)), res);
+var __require = import.meta.require;
+
+// src/ownership.ts
+var StabilityEnum = {
+  Idea: "idea",
+  InCreation: "in_creation",
+  Experimental: "experimental",
+  Beta: "beta",
+  Stable: "stable",
+  Deprecated: "deprecated"
+};
+var OwnersEnum = {
+  PlatformCore: "platform.core",
+  PlatformSigil: "platform.sigil",
+  PlatformMarketplace: "platform.marketplace",
+  PlatformMessaging: "platform.messaging",
+  PlatformContent: "platform.content",
+  PlatformFeatureFlags: "platform.featureflags",
+  PlatformFinance: "platform.finance"
+};
+var Owners = OwnersEnum;
+var TagsEnum = {
+  Spots: "spots",
+  Collectivity: "collectivity",
+  Marketplace: "marketplace",
+  Sellers: "sellers",
+  Auth: "auth",
+  Login: "login",
+  Signup: "signup",
+  Guide: "guide",
+  Docs: "docs",
+  I18n: "i18n",
+  Incident: "incident",
+  Automation: "automation",
+  Hygiene: "hygiene"
+};
+var Tags = TagsEnum;
+export {
+  TagsEnum,
+  Tags,
+  StabilityEnum,
+  OwnersEnum,
+  Owners
+};

package/dist/ownership.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/policy/context.d.ts

@@ -0,0 +1,234 @@
+/**
+ * Runtime policy context for opt-in policy enforcement.
+ *
+ * Provides a context object that can be used to check if a user/tenant
+ * has specific roles, permissions, and attributes at runtime.
+ *
+ * @module policy/context
+ *
+ * @example
+ * ```typescript
+ * import { createPolicyContext } from '@contractspec/lib.contracts-spec';
+ *
+ * // Create context from user's roles and permissions
+ * const ctx = createPolicyContext({
+ *   id: 'user-123',
+ *   tenantId: 'tenant-456',
+ *   roles: ['admin', 'editor'],
+ *   permissions: ['read:articles', 'write:articles'],
+ *   attributes: { department: 'engineering' },
+ * });
+ *
+ * // Check roles and permissions
+ * if (ctx.hasRole('admin')) {
+ *   // User has admin role
+ * }
+ *
+ * // Audit access attempts
+ * ctx.auditAccess('article.update', 'allowed');
+ * ```
+ */
+/**
+ * Error thrown when a policy violation occurs.
+ */
+export declare class PolicyViolationError extends Error {
+    readonly violationType: PolicyViolationType;
+    readonly details: PolicyViolationDetails;
+    constructor(type: PolicyViolationType, details: PolicyViolationDetails);
+}
+export type PolicyViolationType = 'missing_role' | 'missing_permission' | 'missing_attribute' | 'rate_limit_exceeded' | 'consent_required' | 'access_denied';
+export interface PolicyViolationDetails {
+    operation?: string;
+    requiredRole?: string;
+    requiredPermission?: string;
+    requiredAttribute?: {
+        key: string;
+        expected: unknown;
+    };
+    rateLimitKey?: string;
+    consentIds?: string[];
+    reason?: string;
+}
+export interface RateLimitResult {
+    allowed: boolean;
+    remaining: number;
+    resetAt?: Date;
+    retryAfterMs?: number;
+}
+export interface RateLimitState {
+    key: string;
+    count: number;
+    windowStart: number;
+    windowMs: number;
+    limit: number;
+}
+export interface AuditEntry {
+    timestamp: Date;
+    operation: string;
+    result: 'allowed' | 'denied';
+    reason?: string;
+    userId?: string;
+    tenantId?: string;
+    attributes?: Record<string, unknown>;
+}
+export type AuditHandler = (entry: AuditEntry) => void | Promise<void>;
+/**
+ * User information for policy evaluation.
+ */
+export interface PolicyUser {
+    /** Unique user identifier. */
+    id: string;
+    /** Optional tenant/organization ID for multi-tenant contexts. */
+    tenantId?: string;
+    /** Roles assigned to the user. */
+    roles: string[];
+    /** Permissions granted to the user. */
+    permissions: string[];
+    /** Additional attributes for ABAC evaluation. */
+    attributes: Record<string, unknown>;
+}
+/**
+ * Runtime context for checking policy access.
+ *
+ * Created from user information (roles, permissions, attributes).
+ * Provides methods to check and require policy compliance at runtime.
+ */
+export interface PolicyContext {
+    /** The user for this context. */
+    readonly user: PolicyUser;
+    /** Set of user roles. */
+    readonly roles: ReadonlySet<string>;
+    /** Set of user permissions. */
+    readonly permissions: ReadonlySet<string>;
+    /**
+     * Check if user has a specific role.
+     * @param role - Role to check
+     * @returns True if user has the role
+     */
+    hasRole(role: string): boolean;
+    /**
+     * Check if user has any of the specified roles.
+     * @param roles - Roles to check
+     * @returns True if user has at least one role
+     */
+    hasAnyRole(roles: string[]): boolean;
+    /**
+     * Check if user has all of the specified roles.
+     * @param roles - Roles to check
+     * @returns True if user has all roles
+     */
+    hasAllRoles(roles: string[]): boolean;
+    /**
+     * Require a role, throwing if not present.
+     * @param role - Role to require
+     * @throws {PolicyViolationError} If role is missing
+     */
+    requireRole(role: string): void;
+    /**
+     * Check if user has a specific permission.
+     * @param permission - Permission to check
+     * @returns True if user has the permission
+     */
+    hasPermission(permission: string): boolean;
+    /**
+     * Check if user has any of the specified permissions.
+     * @param permissions - Permissions to check
+     * @returns True if user has at least one permission
+     */
+    hasAnyPermission(permissions: string[]): boolean;
+    /**
+     * Check if user has all of the specified permissions.
+     * @param permissions - Permissions to check
+     * @returns True if user has all permissions
+     */
+    hasAllPermissions(permissions: string[]): boolean;
+    /**
+     * Require a permission, throwing if not present.
+     * @param permission - Permission to require
+     * @throws {PolicyViolationError} If permission is missing
+     */
+    requirePermission(permission: string): void;
+    /**
+     * Get a user attribute value.
+     * @param key - Attribute key
+     * @returns Attribute value or undefined
+     */
+    getAttribute<T = unknown>(key: string): T | undefined;
+    /**
+     * Check if an attribute matches an expected value.
+     * @param key - Attribute key
+     * @param expected - Expected value
+     * @returns True if attribute equals expected value
+     */
+    checkAttribute(key: string, expected: unknown): boolean;
+    /**
+     * Check if an attribute is one of the allowed values.
+     * @param key - Attribute key
+     * @param allowedValues - Array of allowed values
+     * @returns True if attribute is in allowed values
+     */
+    checkAttributeOneOf(key: string, allowedValues: unknown[]): boolean;
+    /**
+     * Check rate limit for a key.
+     * @param key - Rate limit key (e.g., operation name)
+     * @returns Rate limit result
+     */
+    checkRateLimit(key: string): RateLimitResult;
+    /**
+     * Consume rate limit for a key (increment counter).
+     * @param key - Rate limit key
+     * @param cost - Cost of the operation (default: 1)
+     * @returns Rate limit result after consumption
+     */
+    consumeRateLimit(key: string, cost?: number): RateLimitResult;
+    /**
+     * Record an access attempt for audit purposes.
+     * @param operation - Operation being accessed
+     * @param result - Whether access was allowed or denied
+     * @param reason - Optional reason for the decision
+     */
+    auditAccess(operation: string, result: 'allowed' | 'denied', reason?: string): void;
+}
+export interface PolicyContextOptions {
+    /** Rate limit configurations by key. */
+    rateLimits?: Record<string, {
+        limit: number;
+        windowMs: number;
+    }>;
+    /** Handler for audit entries. */
+    auditHandler?: AuditHandler;
+}
+/**
+ * Creates a policy context from user information.
+ *
+ * @param user - User information for policy evaluation
+ * @param options - Additional context options
+ * @returns PolicyContext for checking/requiring policy compliance
+ *
+ * @example
+ * ```typescript
+ * const ctx = createPolicyContext({
+ *   id: 'user-123',
+ *   roles: ['editor'],
+ *   permissions: ['read:articles'],
+ *   attributes: { department: 'marketing' },
+ * });
+ *
+ * ctx.requireRole('editor');
+ * ctx.requirePermission('read:articles');
+ * ```
+ */
+export declare function createPolicyContext(user: PolicyUser, options?: PolicyContextOptions): PolicyContext;
+/**
+ * Creates an empty policy context (no roles/permissions).
+ * Useful for anonymous users or testing.
+ */
+export declare function createAnonymousPolicyContext(options?: PolicyContextOptions): PolicyContext;
+/**
+ * Creates a bypass policy context with all roles/permissions.
+ * Useful for admin users or internal services.
+ *
+ * @param allRoles - All roles to grant
+ * @param allPermissions - All permissions to grant
+ */
+export declare function createBypassPolicyContext(allRoles: string[], allPermissions: string[], options?: PolicyContextOptions): PolicyContext;