@xnetjs/core 0.0.2 → 0.1.0

package/dist/index.d.ts

@@ -699,7 +699,7 @@ interface AuthenticatedExpr {
 /**
  * How to determine if a user holds a role.
  */
-type RoleResolver = CreatorRoleResolver | PropertyRoleResolver | RelationRoleResolver;
+type RoleResolver = CreatorRoleResolver | PropertyRoleResolver | RelationRoleResolver | MembershipRoleResolver;
 /**
  * Serialized form of RoleResolver for JSON storage.
  */
@@ -712,6 +712,15 @@ type SerializedRoleResolver = {
     _tag: 'relation';
     relationName: string;
     targetRole: string;
+} | {
+    _tag: 'membership';
+    edgeSchema: string;
+    containerProp: string;
+    memberProp: string;
+    roleProp: string;
+    minRole: string;
+    roleOrder: string[];
+    parentProp?: string;
 };
 /**
  * Role held by the node's creator.
@@ -736,6 +745,34 @@ interface RelationRoleResolver {
     readonly relationName: string;
     readonly targetRole: string;
 }
+/**
+ * Role determined by membership edges that point at THIS node (a reverse-edge
+ * lookup the forward `relation`/`property` resolvers can't express).
+ *
+ * Given a container node (e.g. a Space), the subject holds this role when an
+ * edge node of `edgeSchema` exists whose `containerProp` references this node
+ * (or, when `parentProp` is set, any of its ancestors), whose `memberProp`
+ * holds the subject DID, and whose `roleProp` rank is `>= minRole` per the
+ * `roleOrder` ladder (least → most privileged). The ancestor walk is how
+ * membership cascades down a nested container tree without fanning grants out.
+ */
+interface MembershipRoleResolver {
+    readonly _tag: 'membership';
+    /** Schema IRI of the membership edge node (e.g. SpaceMembership). */
+    readonly edgeSchema: string;
+    /** Edge property that references the container node. */
+    readonly containerProp: string;
+    /** Edge property holding the member DID. */
+    readonly memberProp: string;
+    /** Edge property holding the member's role id. */
+    readonly roleProp: string;
+    /** Minimum role rung this resolver represents. */
+    readonly minRole: string;
+    /** Role ids ordered least → most privileged (for rank comparison). */
+    readonly roleOrder: readonly string[];
+    /** Container relation to walk for ancestor inheritance (e.g. `parent`). */
+    readonly parentProp?: string;
+}
 /**
  * Input for an authorization check.
  */
@@ -770,6 +807,63 @@ interface PolicyEvaluator {
     invalidateSubject(did: DID$1): void;
 }
 
+/**
+ * Small, dependency-free numeric helpers.
+ *
+ * These were independently re-implemented across many packages; this is the
+ * single canonical home for the behaviour-identical variants. Specialized
+ * clampers (`clampRatio`, `clampLimit`, `clampInteger`, …) intentionally stay
+ * local to their callers — they encode caller-specific fallbacks and bounds.
+ */
+/** Clamp `value` into the inclusive `[min, max]` range. */
+declare function clamp(value: number, min: number, max: number): number;
+/** Clamp `value` into the inclusive `[0, 1]` range. */
+declare function clamp01(value: number): number;
+
+/**
+ * Small, dependency-free formatting helpers shared across packages.
+ */
+/**
+ * Format a byte count into a human-readable string using binary (1024) units.
+ *
+ * Canonical replacement for the several `formatBytes`/`formatFileSize` copies
+ * that diverged across packages — notably ones that silently capped at MB and
+ * mis-reported gigabyte-scale sizes. Scales all the way to PB and keeps one
+ * decimal place above the byte unit (e.g. `1536` → `"1.5 KB"`, `0` → `"0 B"`).
+ */
+declare function formatBytes(bytes: number): string;
+
+/**
+ * SSRF guard for server-side / outbound requests.
+ *
+ * A *literal-host* guard (scheme + hostname/IP inspection), not a
+ * post-DNS-resolution guard: a hostname that resolves to a private IP at
+ * request time is not caught here — that deeper check belongs in the fetch
+ * implementation. This closes the common, cheap holes by construction:
+ * non-http(s) schemes, `localhost`, `.local`/`.internal` suffixes, the cloud
+ * metadata host, and private/loopback/link-local IP literals (v4 and v6).
+ *
+ * This is the canonical implementation; `@xnetjs/hub` and `@xnetjs/plugins`
+ * both delegate here so the IP-range logic lives in exactly one place.
+ */
+declare class SsrfError extends Error {
+    readonly url: string;
+    constructor(message: string, url: string);
+}
+/**
+ * Throw {@link SsrfError} unless `rawUrl` is a plausibly-public HTTP(S)
+ * endpoint.
+ */
+declare function assertPublicUrl(rawUrl: string): void;
+/**
+ * Non-throwing variant of {@link assertPublicUrl}: returns `{ valid: true }`
+ * for a public HTTP(S) URL, or `{ valid: false, error }` otherwise.
+ */
+declare function validateExternalUrl(rawUrl: string): {
+    valid: boolean;
+    error?: string;
+};
+
 /**
  * @xnetjs/core - Core types, schemas, and content addressing
  */
@@ -777,4 +871,4 @@ interface PolicyEvaluator {
 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 };
+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 MembershipRoleResolver, 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, SsrfError, type StreamingQueryOptions, type SubQuery, type TimeCondition, type UpdateVerifier, type VectorClock, assertPublicUrl, buildMerkleTree, clamp, clamp01, compareVectorClocks, createChunk, createContentId, deduplicatedUnion, detectFork, estimateQueryCost, evaluateCondition, formatBytes, getMostPermissiveCapability, hashContent, incrementVectorClock, isLocationFresh, isValidDID, isValidProgression, mergeStateVectors, mergeVectorClocks, parseContentId, parseDID, roleHasCapability, shouldCreateSnapshot, unionAggregate, validateExternalUrl, verifyContent, verifyUpdateChain };

package/dist/index.js

@@ -308,6 +308,105 @@ function getMostPermissiveCapability(capabilities) {
 
 // src/auth-types.ts
 var AUTH_ACTIONS = ["read", "write", "delete", "share", "admin"];
+
+// src/utils/math.ts
+function clamp(value, min, max) {
+  if (value < min) return min;
+  if (value > max) return max;
+  return value;
+}
+function clamp01(value) {
+  return clamp(value, 0, 1);
+}
+
+// src/utils/format.ts
+var BYTE_UNITS = ["B", "KB", "MB", "GB", "TB", "PB"];
+function formatBytes(bytes) {
+  if (!Number.isFinite(bytes)) return "\u2014";
+  const negative = bytes < 0;
+  let value = Math.abs(bytes);
+  if (value < 1024) return `${negative ? "-" : ""}${value} B`;
+  let unitIndex = 0;
+  while (value >= 1024 && unitIndex < BYTE_UNITS.length - 1) {
+    value /= 1024;
+    unitIndex += 1;
+  }
+  return `${negative ? "-" : ""}${value.toFixed(1)} ${BYTE_UNITS[unitIndex]}`;
+}
+
+// src/utils/ssrf.ts
+var SsrfError = class extends Error {
+  constructor(message, url) {
+    super(message);
+    this.url = url;
+    this.name = "SsrfError";
+  }
+};
+function parseIpv4(host) {
+  const parts = host.split(".");
+  if (parts.length !== 4) return null;
+  let value = 0;
+  for (const part of parts) {
+    if (!/^\d{1,3}$/.test(part)) return null;
+    const octet = Number(part);
+    if (octet > 255) return null;
+    value = value * 256 + octet;
+  }
+  return value >>> 0;
+}
+function isPrivateIpv4(host) {
+  const ip = parseIpv4(host);
+  if (ip === null) return false;
+  const inRange = (base, bits) => {
+    const baseIp = parseIpv4(base);
+    const mask = bits === 0 ? 0 : 4294967295 << 32 - bits >>> 0;
+    return (ip & mask) === (baseIp & mask);
+  };
+  return inRange("0.0.0.0", 8) || // "this" network / 0.0.0.0
+  inRange("10.0.0.0", 8) || // private
+  inRange("127.0.0.0", 8) || // loopback
+  inRange("169.254.0.0", 16) || // link-local + cloud metadata (169.254.169.254)
+  inRange("172.16.0.0", 12) || // private
+  inRange("192.168.0.0", 16) || // private
+  inRange("100.64.0.0", 10);
+}
+function isBlockedIpv6(host) {
+  const h = host.replace(/^\[|\]$/g, "").toLowerCase();
+  if (h === "::1" || h === "::") return true;
+  if (h.startsWith("fc") || h.startsWith("fd")) return true;
+  if (h.startsWith("::ffff:") || h.startsWith("64:ff9b::")) return true;
+  const firstHextet = parseInt(h.split(":")[0] || "0", 16);
+  if (Number.isFinite(firstHextet) && (firstHextet & 65472) === 65152) return true;
+  return false;
+}
+var BLOCKED_HOSTNAMES = /* @__PURE__ */ new Set(["localhost", "metadata.google.internal"]);
+function assertPublicUrl(rawUrl) {
+  let url;
+  try {
+    url = new URL(rawUrl);
+  } catch {
+    throw new SsrfError(`URL is not valid: ${rawUrl}`, rawUrl);
+  }
+  if (url.protocol !== "http:" && url.protocol !== "https:") {
+    throw new SsrfError(`URL must be http(s): ${rawUrl}`, rawUrl);
+  }
+  const host = url.hostname.toLowerCase().replace(/\.$/, "");
+  if (host.length === 0) {
+    throw new SsrfError(`URL has no hostname: ${rawUrl}`, rawUrl);
+  }
+  const blocked = BLOCKED_HOSTNAMES.has(host) || host.endsWith(".localhost") || host.endsWith(".local") || host.endsWith(".internal") || (host.startsWith("[") ? isBlockedIpv6(host) : isPrivateIpv4(host));
+  if (blocked) {
+    throw new SsrfError(`URL targets a non-public host: ${host}`, rawUrl);
+  }
+}
+function validateExternalUrl(rawUrl) {
+  try {
+    assertPublicUrl(rawUrl);
+    return { valid: true };
+  } catch (error) {
+    return { valid: false, error: error instanceof Error ? error.message : "Invalid URL" };
+  }
+}
 export {
   ALL_CAPABILITIES,
   AUTH_ACTIONS,
@@ -317,7 +416,11 @@ export {
   DHT_CONFIG,
   RESOLUTION_CACHE_CONFIG,
   STANDARD_ROLES,
+  SsrfError,
+  assertPublicUrl,
   buildMerkleTree,
+  clamp,
+  clamp01,
   compareVectorClocks,
   createChunk,
   createContentId,
@@ -325,6 +428,7 @@ export {
   detectFork,
   estimateQueryCost,
   evaluateCondition,
+  formatBytes,
   getMostPermissiveCapability,
   hashContent,
   incrementVectorClock,
@@ -338,6 +442,7 @@ export {
   roleHasCapability,
   shouldCreateSnapshot,
   unionAggregate,
+  validateExternalUrl,
   verifyContent,
   verifyUpdateChain
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xnetjs/core",
-  "version": "0.0.2",
+  "version": "0.1.0",
   "license": "MIT",
   "repository": {
     "type": "git",