@xnetjs/core 0.0.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Chris Smothers
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,66 @@
+# @xnetjs/core
+
+Core types, content addressing, and permission primitives for xNet. This is the leaf package -- it has no internal `@xnetjs/*` dependencies.
+
+## Installation
+
+```bash
+pnpm add @xnetjs/core
+```
+
+## Features
+
+- **Content addressing** -- BLAKE3-based CIDs (`cid:blake3:{hash}`), Merkle trees
+- **Signed updates** -- Vector clocks, signed update types for causal ordering
+- **Snapshots** -- Point-in-time snapshot types for state persistence
+- **Verification** -- Fork detection, update chain verification
+- **DID resolution** -- Pluggable DID resolver interface
+- **Query federation** -- Types for cross-hub federated queries
+- **Permissions** -- Role-based access control (RBAC), capabilities
+
+## Usage
+
+```typescript
+import { hashContent, createContentId, verifyContent, buildMerkleTree } from '@xnetjs/core'
+
+// Hash content with BLAKE3
+const hash = hashContent(new Uint8Array([1, 2, 3]))
+
+// Create a content-addressed ID
+const cid = createContentId(data)
+
+// Verify content integrity
+const isValid = verifyContent(cid, data)
+
+// Build a Merkle tree
+const tree = buildMerkleTree(chunks)
+```
+
+```typescript
+import { detectFork, verifyUpdateChain } from '@xnetjs/core'
+
+// Verify an update chain
+const valid = verifyUpdateChain(updates)
+
+// Detect forks in update history
+const fork = detectFork(chain1, chain2)
+```
+
+## Modules
+
+| Module            | Description                        |
+| ----------------- | ---------------------------------- |
+| `content.ts`      | Content addressing, CID creation   |
+| `hashing.ts`      | BLAKE3 hashing, Merkle trees       |
+| `snapshots.ts`    | Snapshot types and utilities       |
+| `updates.ts`      | Signed updates, vector clocks      |
+| `verification.ts` | Fork detection, chain verification |
+| `resolution.ts`   | DID resolver interface             |
+| `federation.ts`   | Federated query types              |
+| `permissions.ts`  | Roles, capabilities, RBAC          |
+
+## Testing
+
+```bash
+pnpm --filter @xnetjs/core test
+```

package/dist/index.d.ts

@@ -0,0 +1,780 @@
+/**
+ * Content addressing types for xNet
+ */
+/**
+ * Content ID format: cid:blake3:{hash}
+ */
+type ContentId = `cid:blake3:${string}`;
+/**
+ * A chunk of content with its hash
+ */
+interface ContentChunk {
+    data: Uint8Array;
+    hash: string;
+    size: number;
+}
+/**
+ * Merkle tree node for document structure
+ */
+interface MerkleNode {
+    hash: string;
+    children?: string[];
+    data?: Uint8Array;
+}
+/**
+ * Complete content tree for a document
+ */
+interface ContentTree {
+    rootHash: string;
+    nodes: Map<string, MerkleNode>;
+}
+/**
+ * Content resolver interface
+ */
+interface ContentResolver {
+    /** Get content by CID */
+    get(cid: ContentId): Promise<Uint8Array | null>;
+    /** Store content, returns CID */
+    put(data: Uint8Array): Promise<ContentId>;
+    /** Verify content matches CID */
+    verify(cid: ContentId, data: Uint8Array): boolean;
+    /** Build Merkle tree from chunks */
+    buildTree(chunks: ContentChunk[]): ContentTree;
+}
+
+/**
+ * BLAKE3 content hashing for xNet
+ */
+
+/**
+ * Hash content using BLAKE3
+ */
+declare function hashContent(data: Uint8Array): string;
+/**
+ * Create a ContentId from a hash
+ */
+declare function createContentId(hash: string): ContentId;
+/**
+ * Parse a ContentId to extract the hash
+ */
+declare function parseContentId(cid: ContentId): string;
+/**
+ * Verify content matches a CID
+ */
+declare function verifyContent(cid: ContentId, data: Uint8Array): boolean;
+/**
+ * Create a content chunk from data
+ */
+declare function createChunk(data: Uint8Array): ContentChunk;
+/**
+ * Build a Merkle tree from content chunks
+ */
+declare function buildMerkleTree(chunks: ContentChunk[]): ContentTree;
+
+/**
+ * Signed update types for xNet CRDT synchronization
+ */
+/**
+ * Vector clock for tracking causality
+ */
+interface VectorClock {
+    [peerId: string]: number;
+}
+/**
+ * A signed CRDT update with chain linkage
+ */
+interface SignedUpdate {
+    update: Uint8Array;
+    parentHash: string;
+    updateHash: string;
+    authorDID: string;
+    signature: Uint8Array;
+    timestamp: number;
+    vectorClock: VectorClock;
+}
+/**
+ * Represents a fork in the update chain
+ */
+interface Fork {
+    commonAncestor: string;
+    branch1: SignedUpdate[];
+    branch2: SignedUpdate[];
+}
+/**
+ * Update chain status
+ */
+interface ChainStatus {
+    valid: boolean;
+    errors: string[];
+    forks: Fork[];
+}
+/**
+ * Compare two vector clocks
+ * Returns:
+ *  -1 if a < b (a happened before b)
+ *   0 if a || b (concurrent)
+ *   1 if a > b (a happened after b)
+ */
+declare function compareVectorClocks(a: VectorClock, b: VectorClock): -1 | 0 | 1;
+/**
+ * Check if a vector clock progression is valid
+ * The author's clock should increment by exactly 1
+ */
+declare function isValidProgression(prev: VectorClock, next: VectorClock, authorId: string): boolean;
+/**
+ * Merge two vector clocks (take max of each component)
+ */
+declare function mergeVectorClocks(a: VectorClock, b: VectorClock): VectorClock;
+/**
+ * Increment a vector clock for a given peer
+ */
+declare function incrementVectorClock(clock: VectorClock, peerId: string): VectorClock;
+
+/**
+ * Snapshot types and logic for xNet CRDT persistence
+ */
+
+/**
+ * Triggers for when to create a new snapshot
+ */
+interface SnapshotTriggers {
+    updateCount: number;
+    timeInterval: number;
+    storagePressure: number;
+}
+/**
+ * A snapshot represents a compressed CRDT state at a point in time
+ */
+interface Snapshot {
+    id: string;
+    documentId: string;
+    stateVector: Uint8Array;
+    compressedState: Uint8Array;
+    timestamp: number;
+    creatorDID: string;
+    signature: Uint8Array;
+    contentId: ContentId;
+}
+/**
+ * What's needed to load a document
+ */
+interface DocumentLoad {
+    snapshot?: Snapshot;
+    updatesSinceSnapshot: SignedUpdate[];
+}
+/**
+ * Default snapshot triggers
+ */
+declare const DEFAULT_SNAPSHOT_TRIGGERS: SnapshotTriggers;
+/**
+ * Determine if a new snapshot should be created
+ */
+declare function shouldCreateSnapshot(updateCount: number, lastSnapshotTime: number, storageUsed: number, storageTotal: number, triggers?: SnapshotTriggers): boolean;
+/**
+ * Calculate the effective state vector after applying updates
+ */
+declare function mergeStateVectors(base: Uint8Array, _updates: SignedUpdate[]): Uint8Array;
+
+/**
+ * Update verification types and interfaces
+ */
+
+/**
+ * Interface for verifying signed updates
+ */
+interface UpdateVerifier {
+    /** Verify update signature and chain linkage */
+    verify(update: SignedUpdate, publicKey: Uint8Array): Promise<boolean>;
+    /** Detect forks in update chain */
+    detectFork(updates: SignedUpdate[]): Fork | null;
+    /** Check vector clock progression */
+    isValidProgression(prev: VectorClock, next: VectorClock, authorId: string): boolean;
+}
+/**
+ * Detect forks in an update chain
+ * A fork occurs when two updates have the same parent
+ */
+declare function detectFork(updates: SignedUpdate[]): Fork | null;
+/**
+ * Verify an update chain
+ */
+declare function verifyUpdateChain(updates: SignedUpdate[], getPublicKey: (did: string) => Promise<Uint8Array>, verifySignature: (data: Uint8Array, signature: Uint8Array, publicKey: Uint8Array) => boolean): Promise<ChainStatus>;
+
+/**
+ * DID resolution types for xNet peer discovery
+ */
+/**
+ * Location of a peer on the network
+ */
+interface PeerLocation {
+    multiaddr: string;
+    lastSeen: number;
+    latency?: number;
+}
+/**
+ * Result of resolving a DID
+ */
+interface DIDResolution {
+    did: string;
+    publicKey: Uint8Array;
+    locations: PeerLocation[];
+    lastUpdated: number;
+}
+/**
+ * Strategy for resolving DIDs
+ */
+type ResolutionStrategy = 'local-cache' | 'connected-peers' | 'dht' | 'bootstrap';
+/**
+ * Interface for DID resolution
+ */
+interface DIDResolver {
+    /** Resolve DID to locations and public key */
+    resolve(did: string): Promise<DIDResolution | null>;
+    /** Publish own location */
+    publish(did: string, locations: PeerLocation[]): Promise<void>;
+    /** Check cache without network */
+    getCached(did: string): DIDResolution | null;
+}
+/**
+ * Bootstrap peers for initial network discovery
+ */
+declare const BOOTSTRAP_PEERS: readonly ["/dns4/bootstrap1.xnet.io/tcp/4001/p2p/12D3KooWBootstrap1", "/dns4/bootstrap2.xnet.io/tcp/4001/p2p/12D3KooWBootstrap2"];
+/**
+ * DHT configuration for peer discovery
+ */
+declare const DHT_CONFIG: {
+    readonly protocol: "/xnet/kad/1.0.0";
+    readonly replicationFactor: 20;
+    readonly refreshInterval: number;
+};
+/**
+ * Resolution cache configuration
+ */
+declare const RESOLUTION_CACHE_CONFIG: {
+    readonly maxEntries: 1000;
+    readonly ttl: number;
+    readonly staleWhileRevalidate: number;
+};
+/**
+ * Parse a DID to extract the method and identifier
+ */
+declare function parseDID(did: string): {
+    method: string;
+    identifier: string;
+} | null;
+/**
+ * Check if a DID is valid
+ */
+declare function isValidDID(did: string): boolean;
+/**
+ * Check if a location is still considered fresh
+ */
+declare function isLocationFresh(location: PeerLocation, maxAge?: number): boolean;
+
+/**
+ * Query federation types for distributed queries across peers
+ */
+/**
+ * Generic query type (implementation-specific)
+ */
+interface Query {
+    type: string;
+    filters?: Record<string, unknown>;
+    limit?: number;
+    offset?: number;
+    orderBy?: string;
+    orderDirection?: 'asc' | 'desc';
+}
+/**
+ * A data source that can answer queries
+ */
+interface DataSource {
+    type: 'local' | 'peer' | 'cluster';
+    id: string;
+    estimatedLatency: number;
+}
+/**
+ * A subquery to be executed on a specific source
+ */
+interface SubQuery {
+    source: DataSource;
+    query: Query;
+    estimatedCost: number;
+}
+/**
+ * A plan for executing a federated query
+ */
+interface QueryPlan {
+    subqueries: SubQuery[];
+    aggregation: 'union' | 'join' | 'custom';
+    customAggregator?: (results: unknown[][]) => unknown[];
+}
+/**
+ * Interface for routing queries to appropriate sources
+ */
+interface QueryRouter {
+    /** Find which sources have relevant data */
+    findSources(query: Query): Promise<DataSource[]>;
+    /** Route query to source */
+    route(query: Query, source: DataSource): Promise<unknown[]>;
+    /** Aggregate results from multiple sources */
+    aggregate(plan: QueryPlan, results: unknown[][]): unknown[];
+}
+/**
+ * Wire protocol request for federated queries
+ */
+interface QueryRequest {
+    queryId: string;
+    query: Query;
+    auth: string;
+}
+/**
+ * Wire protocol response for federated queries
+ */
+interface QueryResponse {
+    queryId: string;
+    results: unknown[];
+    hasMore: boolean;
+    cursor?: string;
+    error?: string;
+}
+/**
+ * Streaming query options
+ */
+interface StreamingQueryOptions {
+    batchSize: number;
+    timeout: number;
+    maxResults: number;
+}
+/**
+ * Default streaming options
+ */
+declare const DEFAULT_STREAMING_OPTIONS: StreamingQueryOptions;
+/**
+ * Estimate query cost based on filters and limits
+ */
+declare function estimateQueryCost(query: Query): number;
+/**
+ * Simple union aggregation
+ */
+declare function unionAggregate<T>(results: T[][]): T[];
+/**
+ * Deduplicated union aggregation (requires items to have id field)
+ */
+declare function deduplicatedUnion<T extends {
+    id: string;
+}>(results: T[][]): T[];
+
+/**
+ * Permission and authorization types for xNet
+ */
+/**
+ * A group of users
+ */
+interface Group {
+    id: string;
+    members: string[];
+    memberGroups: string[];
+    managedBy: string[];
+}
+/**
+ * A role with associated capabilities
+ */
+interface Role {
+    id: string;
+    capabilities: Capability[];
+}
+/**
+ * Available capabilities
+ */
+type Capability = 'read' | 'write' | 'delete' | 'share' | 'admin';
+/**
+ * All capabilities in order of privilege
+ */
+declare const ALL_CAPABILITIES: Capability[];
+/**
+ * A grant of a role to a principal
+ */
+interface PermissionGrant {
+    principal: string;
+    role: string;
+    scope: ResourceScope;
+    conditions?: Condition[];
+}
+/**
+ * Scope of a permission
+ */
+interface ResourceScope {
+    type: 'workspace' | 'document' | 'block';
+    id: string;
+}
+/**
+ * Conditional access restriction
+ */
+interface Condition {
+    type: 'time' | 'ip' | 'device';
+    value: unknown;
+}
+/**
+ * Time-based condition
+ */
+interface TimeCondition extends Condition {
+    type: 'time';
+    value: {
+        after?: number;
+        before?: number;
+    };
+}
+/**
+ * IP-based condition
+ */
+interface IPCondition extends Condition {
+    type: 'ip';
+    value: {
+        allowList?: string[];
+        denyList?: string[];
+    };
+}
+/**
+ * Interface for evaluating permissions
+ */
+interface PermissionEvaluator {
+    /** Check if DID has capability on resource */
+    hasCapability(did: string, capability: Capability, resource: ResourceScope): Promise<boolean>;
+    /** Resolve group membership (including nested) */
+    resolveGroups(did: string): Promise<string[]>;
+    /** Get effective permissions for DID */
+    getPermissions(did: string, resource: ResourceScope): Promise<Capability[]>;
+}
+/**
+ * Standard roles
+ */
+declare const STANDARD_ROLES: Record<string, Role>;
+/**
+ * Check if a capability is included in a role
+ */
+declare function roleHasCapability(role: Role, capability: Capability): boolean;
+/**
+ * Check if a condition is currently satisfied
+ */
+declare function evaluateCondition(condition: Condition, context: {
+    now?: number;
+}): boolean;
+/**
+ * Get the most permissive capability from a list
+ */
+declare function getMostPermissiveCapability(capabilities: Capability[]): Capability | null;
+
+/**
+ * Authorization types for xNet's encryption-first authorization system.
+ *
+ * These types form the foundation of the authorization model where
+ * "the ability to decrypt" IS access control.
+ */
+/**
+ * DID - Decentralized Identifier for user identity.
+ * Redeclared here to avoid circular imports.
+ */
+type DID$1 = `did:key:${string}`;
+/**
+ * Schema IRI - globally unique identifier for a schema.
+ */
+type SchemaIRI = `xnet://${string}/${string}`;
+/**
+ * Canonical authorization actions.
+ * All action checks map to one of these values.
+ */
+declare const AUTH_ACTIONS: readonly ["read", "write", "delete", "share", "admin"];
+/**
+ * An authorization action that can be checked or granted.
+ */
+type AuthAction = (typeof AUTH_ACTIONS)[number];
+/**
+ * The result of an authorization check.
+ * Contains whether access is allowed plus diagnostic info for debugging.
+ */
+interface AuthDecision {
+    /** Whether the action is permitted */
+    allowed: boolean;
+    /** The action that was checked */
+    action: AuthAction;
+    /** The DID of the subject requesting access */
+    subject: DID$1;
+    /** The resource (node ID) being accessed */
+    resource: string;
+    /** Roles the subject holds that contributed to the decision */
+    roles: string[];
+    /** Grant IDs that contributed to allowing access */
+    grants: string[];
+    /** If denied, the reasons why */
+    reasons: AuthDenyReason[];
+    /** Whether this result came from cache */
+    cached: boolean;
+    /** Timestamp when the decision was evaluated */
+    evaluatedAt: number;
+    /** How long the evaluation took in milliseconds */
+    duration: number;
+}
+/**
+ * Reason codes for authorization denial.
+ * Used for debugging and user-friendly error messages.
+ */
+type AuthDenyReason = 'DENY_NODE_POLICY' | 'DENY_NO_ROLE_MATCH' | 'DENY_NO_GRANT' | 'DENY_UCAN_INVALID' | 'DENY_UCAN_REVOKED' | 'DENY_UCAN_EXPIRED' | 'DENY_DEPTH_EXCEEDED' | 'DENY_NOT_AUTHENTICATED' | 'DENY_FIELD_RESTRICTED' | 'DENY_GRANT_EXPIRED' | 'DENY_STALE_OFFLINE';
+/**
+ * Extended decision with step-by-step evaluation trace.
+ * Used by the explain() API for debugging and AI agent validation.
+ */
+interface AuthTrace extends AuthDecision {
+    /** Each step in the evaluation pipeline */
+    steps: AuthTraceStep[];
+}
+/**
+ * A single step in the authorization evaluation pipeline.
+ */
+interface AuthTraceStep {
+    /** Which phase of evaluation this step represents */
+    phase: 'node-deny' | 'role-resolve' | 'schema-eval' | 'grant-check' | 'public-check';
+    /** Inputs to this evaluation step */
+    input: Record<string, unknown>;
+    /** Outputs from this evaluation step */
+    output: Record<string, unknown>;
+    /** How long this step took in milliseconds */
+    duration: number;
+}
+/**
+ * Authorization rules defined in a schema.
+ *
+ * @example
+ * ```typescript
+ * authorization: {
+ *   roles: {
+ *     owner: role.creator(),
+ *     editor: role.property('editors'),
+ *     admin: role.relation('project', 'admin')
+ *   },
+ *   actions: {
+ *     read: allow('editor', 'admin', 'owner'),
+ *     write: allow('editor', 'admin', 'owner'),
+ *     delete: allow('admin', 'owner'),
+ *     share: allow('admin', 'owner')
+ *   },
+ *   publicProps: ['title']
+ * }
+ * ```
+ */
+interface AuthorizationDefinition<TActions extends Record<string, AuthExpression> = Record<string, AuthExpression>, TRoles extends Record<string, RoleResolver> = Record<string, RoleResolver>> {
+    /** Role definitions - how to determine if a user holds each role */
+    roles: TRoles;
+    /** Action expressions - which roles can perform each action */
+    actions: TActions;
+    /** Properties that are publicly readable even for private nodes */
+    publicProps?: string[];
+    /** Field-level access rules */
+    fieldRules?: Record<string, {
+        allow: AuthExpression;
+        deny?: AuthExpression;
+    }>;
+    /** How node-level policy interacts with schema policy */
+    nodePolicy?: {
+        mode: 'extend';
+        allow: ('deny' | 'fieldRules' | 'conditions')[];
+    };
+}
+/**
+ * Serialized form of AuthorizationDefinition for storage in Schema.
+ */
+interface SerializedAuthorization {
+    roles: Record<string, SerializedRoleResolver>;
+    actions: Record<string, SerializedAuthExpression>;
+    publicProps?: string[];
+    fieldRules?: Record<string, {
+        allow: SerializedAuthExpression;
+        deny?: SerializedAuthExpression;
+    }>;
+    nodePolicy?: {
+        mode: 'extend';
+        allow: string[];
+    };
+}
+/**
+ * Extract action keys from an AuthorizationDefinition.
+ */
+type ActionKey<TAuth extends AuthorizationDefinition> = keyof TAuth['actions'] & string;
+/**
+ * Extract role keys from an AuthorizationDefinition.
+ */
+type RoleKey<TAuth extends AuthorizationDefinition> = keyof TAuth['roles'] & string;
+/**
+ * Extract the action type from a schema with authorization.
+ */
+type SchemaAction<S extends {
+    authorization: AuthorizationDefinition;
+}> = ActionKey<S['authorization']>;
+/**
+ * Authorization expression AST node.
+ * Evaluated against a set of roles to determine access.
+ */
+type AuthExpression = AllowExpr | DenyExpr | AndExpr | OrExpr | NotExpr | RoleRefExpr | PublicExpr | AuthenticatedExpr;
+/**
+ * Serialized form of AuthExpression for JSON storage.
+ */
+type SerializedAuthExpression = {
+    _tag: 'allow';
+    roles: string[];
+} | {
+    _tag: 'deny';
+    roles: string[];
+} | {
+    _tag: 'and';
+    exprs: SerializedAuthExpression[];
+} | {
+    _tag: 'or';
+    exprs: SerializedAuthExpression[];
+} | {
+    _tag: 'not';
+    expr: SerializedAuthExpression;
+} | {
+    _tag: 'roleRef';
+    role: string;
+} | {
+    _tag: 'public';
+} | {
+    _tag: 'authenticated';
+};
+/**
+ * Allow access if the subject has any of the specified roles.
+ */
+interface AllowExpr {
+    readonly _tag: 'allow';
+    readonly roles: readonly string[];
+}
+/**
+ * Deny access if the subject has any of the specified roles.
+ * Deny always takes precedence over allow.
+ */
+interface DenyExpr {
+    readonly _tag: 'deny';
+    readonly roles: readonly string[];
+}
+/**
+ * Logical AND - all sub-expressions must be true.
+ */
+interface AndExpr {
+    readonly _tag: 'and';
+    readonly exprs: readonly AuthExpression[];
+}
+/**
+ * Logical OR - any sub-expression must be true.
+ */
+interface OrExpr {
+    readonly _tag: 'or';
+    readonly exprs: readonly AuthExpression[];
+}
+/**
+ * Logical NOT - negate the sub-expression.
+ */
+interface NotExpr {
+    readonly _tag: 'not';
+    readonly expr: AuthExpression;
+}
+/**
+ * Reference to a named role.
+ */
+interface RoleRefExpr {
+    readonly _tag: 'roleRef';
+    readonly role: string;
+}
+/**
+ * Public access - always allows access.
+ */
+interface PublicExpr {
+    readonly _tag: 'public';
+}
+/**
+ * Authenticated access - allows any authenticated user.
+ */
+interface AuthenticatedExpr {
+    readonly _tag: 'authenticated';
+}
+/**
+ * How to determine if a user holds a role.
+ */
+type RoleResolver = CreatorRoleResolver | PropertyRoleResolver | RelationRoleResolver;
+/**
+ * Serialized form of RoleResolver for JSON storage.
+ */
+type SerializedRoleResolver = {
+    _tag: 'creator';
+} | {
+    _tag: 'property';
+    propertyName: string;
+} | {
+    _tag: 'relation';
+    relationName: string;
+    targetRole: string;
+};
+/**
+ * Role held by the node's creator.
+ */
+interface CreatorRoleResolver {
+    readonly _tag: 'creator';
+}
+/**
+ * Role determined by a person property on the node.
+ * The DID(s) in that property hold this role.
+ */
+interface PropertyRoleResolver {
+    readonly _tag: 'property';
+    readonly propertyName: string;
+}
+/**
+ * Role inherited from a related node.
+ * Users who hold `targetRole` on the related node hold this role.
+ */
+interface RelationRoleResolver {
+    readonly _tag: 'relation';
+    readonly relationName: string;
+    readonly targetRole: string;
+}
+/**
+ * Input for an authorization check.
+ */
+interface AuthCheckInput {
+    /** The DID of the subject requesting access */
+    subject: DID$1;
+    /** The action being requested */
+    action: AuthAction;
+    /** The node being accessed */
+    nodeId: string;
+    /** Pre-loaded node to avoid re-fetching (optional) */
+    node?: {
+        schemaId: SchemaIRI;
+        createdBy: DID$1;
+        properties?: Record<string, unknown>;
+    };
+    /** Patch for field-level checks on update (optional) */
+    patch?: Record<string, unknown>;
+}
+/**
+ * Interface for evaluating authorization policies.
+ * Supersedes the older PermissionEvaluator interface.
+ */
+interface PolicyEvaluator {
+    /** Check if subject can perform action on resource */
+    can(input: AuthCheckInput): Promise<AuthDecision>;
+    /** Check with full trace for debugging */
+    explain(input: AuthCheckInput): Promise<AuthTrace>;
+    /** Invalidate cached decisions for a resource */
+    invalidate(nodeId: string): void;
+    /** Invalidate all cached decisions for a subject */
+    invalidateSubject(did: DID$1): void;
+}
+
+/**
+ * @xnetjs/core - Core types, schemas, and content addressing
+ */
+
+type DID = `did:key:${string}`;
+type DocumentPath = `xnet://${DID}/workspace/${string}/doc/${string}`;
+
+export { ALL_CAPABILITIES, AUTH_ACTIONS, type ActionKey, type AllowExpr, type AndExpr, type AuthAction, type AuthCheckInput, type AuthDecision, type AuthDenyReason, type AuthExpression, type AuthTrace, type AuthTraceStep, type AuthenticatedExpr, type AuthorizationDefinition, BOOTSTRAP_PEERS, type Capability, type ChainStatus, type Condition, type ContentChunk, type ContentId, type ContentResolver, type ContentTree, type CreatorRoleResolver, DEFAULT_SNAPSHOT_TRIGGERS, DEFAULT_STREAMING_OPTIONS, DHT_CONFIG, type DID, type DIDResolution, type DIDResolver, type DataSource, type DenyExpr, type DocumentLoad, type DocumentPath, type Fork, type Group, type IPCondition, type MerkleNode, type NotExpr, type OrExpr, type PeerLocation, type PermissionEvaluator, type PermissionGrant, type PolicyEvaluator, type PropertyRoleResolver, type PublicExpr, type Query, type QueryPlan, type QueryRequest, type QueryResponse, type QueryRouter, RESOLUTION_CACHE_CONFIG, type RelationRoleResolver, type ResolutionStrategy, type ResourceScope, type Role, type RoleKey, type RoleRefExpr, type RoleResolver, STANDARD_ROLES, type SchemaAction, type SerializedAuthExpression, type SerializedAuthorization, type SerializedRoleResolver, type SignedUpdate, type Snapshot, type SnapshotTriggers, type StreamingQueryOptions, type SubQuery, type TimeCondition, type UpdateVerifier, type VectorClock, buildMerkleTree, compareVectorClocks, createChunk, createContentId, deduplicatedUnion, detectFork, estimateQueryCost, evaluateCondition, getMostPermissiveCapability, hashContent, incrementVectorClock, isLocationFresh, isValidDID, isValidProgression, mergeStateVectors, mergeVectorClocks, parseContentId, parseDID, roleHasCapability, shouldCreateSnapshot, unionAggregate, verifyContent, verifyUpdateChain };

package/dist/index.js

@@ -0,0 +1,343 @@
+// src/hashing.ts
+import { blake3 } from "@noble/hashes/blake3.js";
+function hashContent(data) {
+  const hash = blake3(data);
+  return bytesToHex(hash);
+}
+function createContentId(hash) {
+  return `cid:blake3:${hash}`;
+}
+function parseContentId(cid) {
+  const match = cid.match(/^cid:blake3:([a-f0-9]+)$/);
+  if (!match) throw new Error(`Invalid CID: ${cid}`);
+  return match[1];
+}
+function verifyContent(cid, data) {
+  const expectedHash = parseContentId(cid);
+  const actualHash = hashContent(data);
+  return expectedHash === actualHash;
+}
+function createChunk(data) {
+  return {
+    data,
+    hash: hashContent(data),
+    size: data.length
+  };
+}
+function buildMerkleTree(chunks) {
+  const nodes = /* @__PURE__ */ new Map();
+  if (chunks.length === 0) {
+    const emptyHash = hashContent(new Uint8Array(0));
+    nodes.set(emptyHash, { hash: emptyHash, data: new Uint8Array(0) });
+    return { rootHash: emptyHash, nodes };
+  }
+  const leafHashes = [];
+  for (const chunk of chunks) {
+    nodes.set(chunk.hash, {
+      hash: chunk.hash,
+      data: chunk.data
+    });
+    leafHashes.push(chunk.hash);
+  }
+  let currentLevel = leafHashes;
+  while (currentLevel.length > 1) {
+    const nextLevel = [];
+    for (let i = 0; i < currentLevel.length; i += 2) {
+      const left = currentLevel[i];
+      const right = currentLevel[i + 1] || left;
+      const combined = new TextEncoder().encode(left + right);
+      const parentHash = hashContent(combined);
+      nodes.set(parentHash, {
+        hash: parentHash,
+        children: left === right ? [left] : [left, right]
+      });
+      nextLevel.push(parentHash);
+    }
+    currentLevel = nextLevel;
+  }
+  return {
+    rootHash: currentLevel[0],
+    nodes
+  };
+}
+function bytesToHex(bytes) {
+  return Array.from(bytes).map((b) => b.toString(16).padStart(2, "0")).join("");
+}
+
+// src/snapshots.ts
+var DEFAULT_SNAPSHOT_TRIGGERS = {
+  updateCount: 1e4,
+  timeInterval: 24 * 60 * 60 * 1e3,
+  // 24 hours
+  storagePressure: 0.8
+  // 80%
+};
+function shouldCreateSnapshot(updateCount, lastSnapshotTime, storageUsed, storageTotal, triggers = DEFAULT_SNAPSHOT_TRIGGERS) {
+  if (updateCount >= triggers.updateCount) return true;
+  if (Date.now() - lastSnapshotTime >= triggers.timeInterval) return true;
+  if (storageTotal > 0 && storageUsed / storageTotal >= triggers.storagePressure) return true;
+  return false;
+}
+function mergeStateVectors(base, _updates) {
+  return base;
+}
+
+// src/updates.ts
+function compareVectorClocks(a, b) {
+  const allKeys = /* @__PURE__ */ new Set([...Object.keys(a), ...Object.keys(b)]);
+  let aGreater = false;
+  let bGreater = false;
+  for (const key of allKeys) {
+    const aVal = a[key] || 0;
+    const bVal = b[key] || 0;
+    if (aVal > bVal) aGreater = true;
+    if (bVal > aVal) bGreater = true;
+  }
+  if (aGreater && !bGreater) return 1;
+  if (bGreater && !aGreater) return -1;
+  return 0;
+}
+function isValidProgression(prev, next, authorId) {
+  const prevAuthor = prev[authorId] || 0;
+  const nextAuthor = next[authorId] || 0;
+  if (nextAuthor !== prevAuthor + 1) return false;
+  for (const key of Object.keys(prev)) {
+    if (key !== authorId) {
+      const prevVal = prev[key] || 0;
+      const nextVal = next[key] || 0;
+      if (nextVal < prevVal) return false;
+    }
+  }
+  return true;
+}
+function mergeVectorClocks(a, b) {
+  const result = { ...a };
+  for (const [key, value] of Object.entries(b)) {
+    result[key] = Math.max(result[key] || 0, value);
+  }
+  return result;
+}
+function incrementVectorClock(clock, peerId) {
+  return {
+    ...clock,
+    [peerId]: (clock[peerId] || 0) + 1
+  };
+}
+
+// src/verification.ts
+function detectFork(updates) {
+  const byParent = /* @__PURE__ */ new Map();
+  for (const update of updates) {
+    const existing = byParent.get(update.parentHash) || [];
+    existing.push(update);
+    byParent.set(update.parentHash, existing);
+  }
+  for (const [parentHash, children] of byParent) {
+    if (children.length > 1) {
+      const branch1 = buildBranch(children[0], updates);
+      const branch2 = buildBranch(children[1], updates);
+      return {
+        commonAncestor: parentHash,
+        branch1,
+        branch2
+      };
+    }
+  }
+  return null;
+}
+function buildBranch(start, allUpdates) {
+  const branch = [start];
+  const byParent = /* @__PURE__ */ new Map();
+  for (const update of allUpdates) {
+    byParent.set(update.parentHash, update);
+  }
+  let current = start;
+  while (true) {
+    const next = byParent.get(current.updateHash);
+    if (!next) break;
+    branch.push(next);
+    current = next;
+  }
+  return branch;
+}
+async function verifyUpdateChain(updates, getPublicKey, verifySignature) {
+  const errors = [];
+  const forks = [];
+  const sorted = [...updates].sort((a, b) => a.timestamp - b.timestamp);
+  const fork = detectFork(sorted);
+  if (fork) {
+    forks.push(fork);
+    errors.push(`Fork detected at ${fork.commonAncestor}`);
+  }
+  for (let i = 0; i < sorted.length; i++) {
+    const update = sorted[i];
+    let publicKey;
+    try {
+      publicKey = await getPublicKey(update.authorDID);
+    } catch {
+      errors.push(`Failed to get public key for ${update.authorDID}`);
+      continue;
+    }
+    const signatureData = new Uint8Array([
+      ...update.update,
+      ...new TextEncoder().encode(update.parentHash),
+      ...new TextEncoder().encode(update.authorDID),
+      ...new TextEncoder().encode(update.timestamp.toString())
+    ]);
+    if (!verifySignature(signatureData, update.signature, publicKey)) {
+      errors.push(`Invalid signature for update ${update.updateHash}`);
+    }
+    if (i > 0) {
+      const prev = sorted[i - 1];
+      if (update.parentHash === prev.updateHash) {
+        if (!isValidProgression(prev.vectorClock, update.vectorClock, update.authorDID)) {
+          errors.push(`Invalid vector clock progression at ${update.updateHash}`);
+        }
+      }
+    }
+  }
+  return {
+    valid: errors.length === 0,
+    errors,
+    forks
+  };
+}
+
+// src/resolution.ts
+var BOOTSTRAP_PEERS = [
+  "/dns4/bootstrap1.xnet.io/tcp/4001/p2p/12D3KooWBootstrap1",
+  "/dns4/bootstrap2.xnet.io/tcp/4001/p2p/12D3KooWBootstrap2"
+  // Real peers added at deployment
+];
+var DHT_CONFIG = {
+  protocol: "/xnet/kad/1.0.0",
+  replicationFactor: 20,
+  refreshInterval: 60 * 60 * 1e3
+  // 1 hour
+};
+var RESOLUTION_CACHE_CONFIG = {
+  maxEntries: 1e3,
+  ttl: 5 * 60 * 1e3,
+  // 5 minutes
+  staleWhileRevalidate: 60 * 60 * 1e3
+  // 1 hour
+};
+function parseDID(did) {
+  const match = did.match(/^did:([a-z]+):(.+)$/);
+  if (!match) return null;
+  return { method: match[1], identifier: match[2] };
+}
+function isValidDID(did) {
+  return parseDID(did) !== null;
+}
+function isLocationFresh(location, maxAge = 5 * 60 * 1e3) {
+  return Date.now() - location.lastSeen < maxAge;
+}
+
+// src/federation.ts
+var DEFAULT_STREAMING_OPTIONS = {
+  batchSize: 100,
+  timeout: 3e4,
+  // 30 seconds
+  maxResults: 1e4
+};
+function estimateQueryCost(query) {
+  let cost = 1;
+  const filterCount = Object.keys(query.filters || {}).length;
+  cost *= Math.max(0.1, 1 - filterCount * 0.1);
+  if (query.limit) {
+    cost *= Math.min(1, query.limit / 1e3);
+  }
+  return cost;
+}
+function unionAggregate(results) {
+  return results.flat();
+}
+function deduplicatedUnion(results) {
+  const seen = /* @__PURE__ */ new Set();
+  const output = [];
+  for (const batch of results) {
+    for (const item of batch) {
+      if (!seen.has(item.id)) {
+        seen.add(item.id);
+        output.push(item);
+      }
+    }
+  }
+  return output;
+}
+
+// src/permissions.ts
+var ALL_CAPABILITIES = ["read", "write", "delete", "share", "admin"];
+var STANDARD_ROLES = {
+  viewer: {
+    id: "viewer",
+    capabilities: ["read"]
+  },
+  editor: {
+    id: "editor",
+    capabilities: ["read", "write"]
+  },
+  admin: {
+    id: "admin",
+    capabilities: ["read", "write", "delete", "share", "admin"]
+  }
+};
+function roleHasCapability(role, capability) {
+  return role.capabilities.includes(capability);
+}
+function evaluateCondition(condition, context) {
+  switch (condition.type) {
+    case "time": {
+      const timeCondition = condition;
+      const now = context.now || Date.now();
+      if (timeCondition.value.after && now < timeCondition.value.after) return false;
+      if (timeCondition.value.before && now > timeCondition.value.before) return false;
+      return true;
+    }
+    default:
+      return true;
+  }
+}
+function getMostPermissiveCapability(capabilities) {
+  for (const cap of [...ALL_CAPABILITIES].reverse()) {
+    if (capabilities.includes(cap)) return cap;
+  }
+  return null;
+}
+
+// src/auth-types.ts
+var AUTH_ACTIONS = ["read", "write", "delete", "share", "admin"];
+export {
+  ALL_CAPABILITIES,
+  AUTH_ACTIONS,
+  BOOTSTRAP_PEERS,
+  DEFAULT_SNAPSHOT_TRIGGERS,
+  DEFAULT_STREAMING_OPTIONS,
+  DHT_CONFIG,
+  RESOLUTION_CACHE_CONFIG,
+  STANDARD_ROLES,
+  buildMerkleTree,
+  compareVectorClocks,
+  createChunk,
+  createContentId,
+  deduplicatedUnion,
+  detectFork,
+  estimateQueryCost,
+  evaluateCondition,
+  getMostPermissiveCapability,
+  hashContent,
+  incrementVectorClock,
+  isLocationFresh,
+  isValidDID,
+  isValidProgression,
+  mergeStateVectors,
+  mergeVectorClocks,
+  parseContentId,
+  parseDID,
+  roleHasCapability,
+  shouldCreateSnapshot,
+  unionAggregate,
+  verifyContent,
+  verifyUpdateChain
+};

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@xnetjs/core",
+  "version": "0.0.2",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/crs48/xNet"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "devDependencies": {
+    "tsup": "^8.0.0",
+    "typescript": "^5.4.0"
+  },
+  "dependencies": {
+    "@noble/hashes": "^2.0.1"
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --dts",
+    "typecheck": "tsc --noEmit",
+    "clean": "rm -rf dist"
+  }
+}