@tinycloud/sdk-core 2.2.0-beta.1 → 2.2.0-beta.4

package/dist/index.d.cts

@@ -4437,4 +4437,103 @@ interface NodeInfo {
 }
 declare function checkNodeInfo(host: string, sdkProtocol: number, fetchFn?: typeof globalThis.fetch): Promise<NodeInfo>;
 
-export { ACCOUNT_REGISTRY_PATH, ACCOUNT_REGISTRY_SPACE, type AbilitiesMap, AutoApproveSpaceCreationHandler, type AutoRejectStrategy, type AutoSignStrategy, type Bytes, type CallbackStrategy, type CapabilityEntry, CapabilityKeyRegistry, type CapabilityKeyRegistryErrorCode, CapabilityKeyRegistryErrorCodes, type ClientSession, ClientSessionSchema, type ComposeManifestOptions, type ComposedManifestRequest, type CreateDelegationFunction, type CreateDelegationParams, type CreateDelegationWasmParams, type CreateDelegationWasmResult, DEFAULT_DEFAULTS, DEFAULT_EXPIRY, DEFAULT_MANIFEST_SPACE, DEFAULT_MANIFEST_VERSION, type DelegatedResource, type Delegation, type DelegationApiResponse, type DelegationChain, type DelegationChainV2, type DelegationDirection, type DelegationError, type DelegationErrorCode, DelegationErrorCodes, type DelegationFilters, DelegationManager, type DelegationManagerConfig, type DelegationRecord, type Result as DelegationResult, type EncodedShareData, type EnsData, EnsDataSchema, type EventEmitterStrategy, type Extension, type GenerateShareParams, type ICapabilityKeyRegistry, type IENSResolver, type INotificationHandler, type ISessionManager, type ISessionStorage, type ISharingService, type ISigner, type ISpace, type ISpaceCreationHandler, type ISpaceScopedDelegations, type ISpaceScopedSharing, type ISpaceService, type IUserAuthorization, type IWasmBindings, type IngestOptions, type JWK, type KeyInfo, type KeyProvider, type KeyType, type Manifest, type ManifestDefaults, type ManifestRegistryRecord, ManifestValidationError, type NodeInfo, type ParseRecapFromSiwe, type PartialSiweMessage, type PermissionEntry, PermissionNotInManifestError, type PersistedSessionData, type PersistedTinyCloudSession, ProtocolMismatchError, type ReceiveOptions, type ResolvedCapabilities, type ResolvedDelegate, type ResourceCapability, SERVICE_LONG_TO_SHORT, SERVICE_SHORT_TO_LONG, type ServerHost, SessionExpiredError, type ShareAccess, type ShareLink, type ShareLinkData, type ShareSchema, SharingService, type SharingServiceConfig, type SignCallback, type SignInOptions, type SignRequest, type SignResponse, type SignStrategy, SilentNotificationHandler, type SiweConfig, SiweConfigSchema, Space, type SpaceAbilitiesMap, type SpaceConfig, type SpaceCreationContext, type SpaceDelegationParams, type SpaceErrorCode, SpaceErrorCodes, type SpaceHostResult, type SpaceInfo, type SpaceOwnership, SpaceService, type SpaceServiceConfig, type StoredDelegationChain, type SubsetCheckResult, TinyCloud, type TinyCloudConfig, type TinyCloudSession, UnsupportedFeatureError, type UserAuthorizationConfig, type ValidationError, VersionCheckError, type WasmRecapEntry, activateSessionWithHost, applyPrefix, buildSpaceUri, checkNodeInfo, composeManifestRequest, createCapabilityKeyRegistry, createSharingService, createSpaceService, defaultSignStrategy, defaultSpaceCreationHandler, expandActionShortNames, fetchPeerId, isCapabilitySubset, loadManifest, makePublicSpaceId, manifestAbilitiesUnion, normalizeDefaults, parseExpiry, parseRecapCapabilities, parseSpaceUri, resolveManifest, resourceCapabilitiesToAbilitiesMap, resourceCapabilitiesToSpaceAbilitiesMap, submitHostDelegation, validateClientSession, validateManifest, validatePersistedSessionData };
+/**
+ * TinyCloud location registry helpers.
+ *
+ * The registry maps a DID to one or more multiaddrs. Registry records are
+ * signed by the DID subject; centralized storage is only a discovery cache.
+ */
+interface LocationRecordPayload {
+    version: 1;
+    subject: string;
+    multiaddrs: string[];
+    updated_at: string;
+    sequence: number;
+}
+interface LocationRecord extends LocationRecordPayload {
+    signature: string;
+}
+type LocationSource = "explicit" | "blockchain" | "centralized" | "fallback";
+declare const DEFAULT_TINYCLOUD_LOCATION_REGISTRY_URL = "https://registry.tinycloud.xyz";
+declare const DEFAULT_TINYCLOUD_FALLBACK_HOST = "https://node.tinycloud.xyz";
+interface LocationCandidate {
+    source: LocationSource;
+    multiaddrs: string[];
+    record?: LocationRecord;
+}
+interface LocationResolutionAttempt {
+    source: LocationSource;
+    candidate?: LocationCandidate;
+    error?: Error;
+}
+interface ResolvedCloudLocation {
+    subject: string;
+    source: LocationSource;
+    multiaddrs: string[];
+    record?: LocationRecord;
+    attempts: LocationResolutionAttempt[];
+    resolvedAt: string;
+}
+interface ResolveCloudLocationOptions {
+    /** Highest-priority location supplied directly by the caller. */
+    explicitMultiaddrs?: string[];
+    /** Optional blockchain resolver adapter. */
+    blockchain?: (subject: string) => Promise<LocationCandidateInput | null | undefined>;
+    /** Centralized location registry base URL, e.g. https://registry.tinycloud.xyz. */
+    centralizedRegistryUrl?: string;
+    /** Lowest-priority fallback location. */
+    fallbackMultiaddrs?: string[];
+    /** Custom fetch implementation. Defaults to globalThis.fetch. */
+    fetch?: typeof fetch;
+    /** Verify centralized/blockchain record signatures. Default true. */
+    verifyRecords?: boolean;
+}
+interface ResolvedTinyCloudHosts {
+    hosts: string[];
+    location: ResolvedCloudLocation;
+}
+interface ResolveTinyCloudHostsOptions {
+    /** Highest-priority TinyCloud HTTP host URLs or multiaddrs supplied directly. */
+    explicitHosts?: string[];
+    /** Optional blockchain resolver adapter. */
+    blockchain?: ResolveCloudLocationOptions["blockchain"];
+    /** Centralized location registry URL. Default https://registry.tinycloud.xyz. */
+    registryUrl?: string | null;
+    /** Lowest-priority fallback HTTP host URLs or multiaddrs. Default hosted TinyCloud node. */
+    fallbackHosts?: string[] | null;
+    /** Custom fetch implementation. Defaults to globalThis.fetch. */
+    fetch?: typeof fetch;
+    /** Verify centralized/blockchain record signatures. Default true. */
+    verifyRecords?: boolean;
+}
+type LocationCandidateInput = string[] | LocationRecord | {
+    multiaddrs: string[];
+    record?: LocationRecord;
+};
+type LocationRecordSigner = {
+    type: "did:pkh";
+    signMessage(message: string): Promise<string>;
+} | {
+    type: "did:key";
+    signBytes(bytes: Uint8Array): Promise<Uint8Array>;
+};
+declare class LocationRecordValidationError extends Error {
+    constructor(message: string);
+}
+declare class CloudLocationResolutionError extends Error {
+    readonly attempts: LocationResolutionAttempt[];
+    constructor(subject: string, attempts: LocationResolutionAttempt[]);
+}
+declare function locationPayloadForRecord(record: LocationRecord): LocationRecordPayload;
+declare function canonicalLocationPayload(payload: LocationRecordPayload): string;
+declare function signLocationRecord(payload: LocationRecordPayload, signer: LocationRecordSigner): Promise<LocationRecord>;
+declare function validateLocationRecordPayload(input: unknown): LocationRecordPayload;
+declare function validateLocationRecord(input: unknown): LocationRecord;
+declare function verifyLocationRecord(input: LocationRecord): Promise<boolean>;
+declare function fetchLocationRecord(registryUrl: string, subject: string, fetchFn?: typeof fetch): Promise<LocationRecord | null>;
+declare function resolveCloudLocation(subject: string, options?: ResolveCloudLocationOptions): Promise<ResolvedCloudLocation>;
+declare function resolveTinyCloudHosts(subject: string, options?: ResolveTinyCloudHostsOptions): Promise<ResolvedTinyCloudHosts>;
+declare function multiaddrToHttpUrl(input: string): string;
+declare function httpUrlToMultiaddr(input: string): string;
+
+export { ACCOUNT_REGISTRY_PATH, ACCOUNT_REGISTRY_SPACE, type AbilitiesMap, AutoApproveSpaceCreationHandler, type AutoRejectStrategy, type AutoSignStrategy, type Bytes, type CallbackStrategy, type CapabilityEntry, CapabilityKeyRegistry, type CapabilityKeyRegistryErrorCode, CapabilityKeyRegistryErrorCodes, type ClientSession, ClientSessionSchema, CloudLocationResolutionError, type ComposeManifestOptions, type ComposedManifestRequest, type CreateDelegationFunction, type CreateDelegationParams, type CreateDelegationWasmParams, type CreateDelegationWasmResult, DEFAULT_DEFAULTS, DEFAULT_EXPIRY, DEFAULT_MANIFEST_SPACE, DEFAULT_MANIFEST_VERSION, DEFAULT_TINYCLOUD_FALLBACK_HOST, DEFAULT_TINYCLOUD_LOCATION_REGISTRY_URL, type DelegatedResource, type Delegation, type DelegationApiResponse, type DelegationChain, type DelegationChainV2, type DelegationDirection, type DelegationError, type DelegationErrorCode, DelegationErrorCodes, type DelegationFilters, DelegationManager, type DelegationManagerConfig, type DelegationRecord, type Result as DelegationResult, type EncodedShareData, type EnsData, EnsDataSchema, type EventEmitterStrategy, type Extension, type GenerateShareParams, type ICapabilityKeyRegistry, type IENSResolver, type INotificationHandler, type ISessionManager, type ISessionStorage, type ISharingService, type ISigner, type ISpace, type ISpaceCreationHandler, type ISpaceScopedDelegations, type ISpaceScopedSharing, type ISpaceService, type IUserAuthorization, type IWasmBindings, type IngestOptions, type JWK, type KeyInfo, type KeyProvider, type KeyType, type LocationCandidate, type LocationCandidateInput, type LocationRecord, type LocationRecordPayload, type LocationRecordSigner, LocationRecordValidationError, type LocationResolutionAttempt, type LocationSource, type Manifest, type ManifestDefaults, type ManifestRegistryRecord, ManifestValidationError, type NodeInfo, type ParseRecapFromSiwe, type PartialSiweMessage, type PermissionEntry, PermissionNotInManifestError, type PersistedSessionData, type PersistedTinyCloudSession, ProtocolMismatchError, type ReceiveOptions, type ResolveCloudLocationOptions, type ResolveTinyCloudHostsOptions, type ResolvedCapabilities, type ResolvedCloudLocation, type ResolvedDelegate, type ResolvedTinyCloudHosts, type ResourceCapability, SERVICE_LONG_TO_SHORT, SERVICE_SHORT_TO_LONG, type ServerHost, SessionExpiredError, type ShareAccess, type ShareLink, type ShareLinkData, type ShareSchema, SharingService, type SharingServiceConfig, type SignCallback, type SignInOptions, type SignRequest, type SignResponse, type SignStrategy, SilentNotificationHandler, type SiweConfig, SiweConfigSchema, Space, type SpaceAbilitiesMap, type SpaceConfig, type SpaceCreationContext, type SpaceDelegationParams, type SpaceErrorCode, SpaceErrorCodes, type SpaceHostResult, type SpaceInfo, type SpaceOwnership, SpaceService, type SpaceServiceConfig, type StoredDelegationChain, type SubsetCheckResult, TinyCloud, type TinyCloudConfig, type TinyCloudSession, UnsupportedFeatureError, type UserAuthorizationConfig, type ValidationError, VersionCheckError, type WasmRecapEntry, activateSessionWithHost, applyPrefix, buildSpaceUri, canonicalLocationPayload, checkNodeInfo, composeManifestRequest, createCapabilityKeyRegistry, createSharingService, createSpaceService, defaultSignStrategy, defaultSpaceCreationHandler, expandActionShortNames, fetchLocationRecord, fetchPeerId, httpUrlToMultiaddr, isCapabilitySubset, loadManifest, locationPayloadForRecord, makePublicSpaceId, manifestAbilitiesUnion, multiaddrToHttpUrl, normalizeDefaults, parseExpiry, parseRecapCapabilities, parseSpaceUri, resolveCloudLocation, resolveManifest, resolveTinyCloudHosts, resourceCapabilitiesToAbilitiesMap, resourceCapabilitiesToSpaceAbilitiesMap, signLocationRecord, submitHostDelegation, validateClientSession, validateLocationRecord, validateLocationRecordPayload, validateManifest, validatePersistedSessionData, verifyLocationRecord };

package/dist/index.d.ts

@@ -4437,4 +4437,103 @@ interface NodeInfo {
 }
 declare function checkNodeInfo(host: string, sdkProtocol: number, fetchFn?: typeof globalThis.fetch): Promise<NodeInfo>;
 
-export { ACCOUNT_REGISTRY_PATH, ACCOUNT_REGISTRY_SPACE, type AbilitiesMap, AutoApproveSpaceCreationHandler, type AutoRejectStrategy, type AutoSignStrategy, type Bytes, type CallbackStrategy, type CapabilityEntry, CapabilityKeyRegistry, type CapabilityKeyRegistryErrorCode, CapabilityKeyRegistryErrorCodes, type ClientSession, ClientSessionSchema, type ComposeManifestOptions, type ComposedManifestRequest, type CreateDelegationFunction, type CreateDelegationParams, type CreateDelegationWasmParams, type CreateDelegationWasmResult, DEFAULT_DEFAULTS, DEFAULT_EXPIRY, DEFAULT_MANIFEST_SPACE, DEFAULT_MANIFEST_VERSION, type DelegatedResource, type Delegation, type DelegationApiResponse, type DelegationChain, type DelegationChainV2, type DelegationDirection, type DelegationError, type DelegationErrorCode, DelegationErrorCodes, type DelegationFilters, DelegationManager, type DelegationManagerConfig, type DelegationRecord, type Result as DelegationResult, type EncodedShareData, type EnsData, EnsDataSchema, type EventEmitterStrategy, type Extension, type GenerateShareParams, type ICapabilityKeyRegistry, type IENSResolver, type INotificationHandler, type ISessionManager, type ISessionStorage, type ISharingService, type ISigner, type ISpace, type ISpaceCreationHandler, type ISpaceScopedDelegations, type ISpaceScopedSharing, type ISpaceService, type IUserAuthorization, type IWasmBindings, type IngestOptions, type JWK, type KeyInfo, type KeyProvider, type KeyType, type Manifest, type ManifestDefaults, type ManifestRegistryRecord, ManifestValidationError, type NodeInfo, type ParseRecapFromSiwe, type PartialSiweMessage, type PermissionEntry, PermissionNotInManifestError, type PersistedSessionData, type PersistedTinyCloudSession, ProtocolMismatchError, type ReceiveOptions, type ResolvedCapabilities, type ResolvedDelegate, type ResourceCapability, SERVICE_LONG_TO_SHORT, SERVICE_SHORT_TO_LONG, type ServerHost, SessionExpiredError, type ShareAccess, type ShareLink, type ShareLinkData, type ShareSchema, SharingService, type SharingServiceConfig, type SignCallback, type SignInOptions, type SignRequest, type SignResponse, type SignStrategy, SilentNotificationHandler, type SiweConfig, SiweConfigSchema, Space, type SpaceAbilitiesMap, type SpaceConfig, type SpaceCreationContext, type SpaceDelegationParams, type SpaceErrorCode, SpaceErrorCodes, type SpaceHostResult, type SpaceInfo, type SpaceOwnership, SpaceService, type SpaceServiceConfig, type StoredDelegationChain, type SubsetCheckResult, TinyCloud, type TinyCloudConfig, type TinyCloudSession, UnsupportedFeatureError, type UserAuthorizationConfig, type ValidationError, VersionCheckError, type WasmRecapEntry, activateSessionWithHost, applyPrefix, buildSpaceUri, checkNodeInfo, composeManifestRequest, createCapabilityKeyRegistry, createSharingService, createSpaceService, defaultSignStrategy, defaultSpaceCreationHandler, expandActionShortNames, fetchPeerId, isCapabilitySubset, loadManifest, makePublicSpaceId, manifestAbilitiesUnion, normalizeDefaults, parseExpiry, parseRecapCapabilities, parseSpaceUri, resolveManifest, resourceCapabilitiesToAbilitiesMap, resourceCapabilitiesToSpaceAbilitiesMap, submitHostDelegation, validateClientSession, validateManifest, validatePersistedSessionData };
+/**
+ * TinyCloud location registry helpers.
+ *
+ * The registry maps a DID to one or more multiaddrs. Registry records are
+ * signed by the DID subject; centralized storage is only a discovery cache.
+ */
+interface LocationRecordPayload {
+    version: 1;
+    subject: string;
+    multiaddrs: string[];
+    updated_at: string;
+    sequence: number;
+}
+interface LocationRecord extends LocationRecordPayload {
+    signature: string;
+}
+type LocationSource = "explicit" | "blockchain" | "centralized" | "fallback";
+declare const DEFAULT_TINYCLOUD_LOCATION_REGISTRY_URL = "https://registry.tinycloud.xyz";
+declare const DEFAULT_TINYCLOUD_FALLBACK_HOST = "https://node.tinycloud.xyz";
+interface LocationCandidate {
+    source: LocationSource;
+    multiaddrs: string[];
+    record?: LocationRecord;
+}
+interface LocationResolutionAttempt {
+    source: LocationSource;
+    candidate?: LocationCandidate;
+    error?: Error;
+}
+interface ResolvedCloudLocation {
+    subject: string;
+    source: LocationSource;
+    multiaddrs: string[];
+    record?: LocationRecord;
+    attempts: LocationResolutionAttempt[];
+    resolvedAt: string;
+}
+interface ResolveCloudLocationOptions {
+    /** Highest-priority location supplied directly by the caller. */
+    explicitMultiaddrs?: string[];
+    /** Optional blockchain resolver adapter. */
+    blockchain?: (subject: string) => Promise<LocationCandidateInput | null | undefined>;
+    /** Centralized location registry base URL, e.g. https://registry.tinycloud.xyz. */
+    centralizedRegistryUrl?: string;
+    /** Lowest-priority fallback location. */
+    fallbackMultiaddrs?: string[];
+    /** Custom fetch implementation. Defaults to globalThis.fetch. */
+    fetch?: typeof fetch;
+    /** Verify centralized/blockchain record signatures. Default true. */
+    verifyRecords?: boolean;
+}
+interface ResolvedTinyCloudHosts {
+    hosts: string[];
+    location: ResolvedCloudLocation;
+}
+interface ResolveTinyCloudHostsOptions {
+    /** Highest-priority TinyCloud HTTP host URLs or multiaddrs supplied directly. */
+    explicitHosts?: string[];
+    /** Optional blockchain resolver adapter. */
+    blockchain?: ResolveCloudLocationOptions["blockchain"];
+    /** Centralized location registry URL. Default https://registry.tinycloud.xyz. */
+    registryUrl?: string | null;
+    /** Lowest-priority fallback HTTP host URLs or multiaddrs. Default hosted TinyCloud node. */
+    fallbackHosts?: string[] | null;
+    /** Custom fetch implementation. Defaults to globalThis.fetch. */
+    fetch?: typeof fetch;
+    /** Verify centralized/blockchain record signatures. Default true. */
+    verifyRecords?: boolean;
+}
+type LocationCandidateInput = string[] | LocationRecord | {
+    multiaddrs: string[];
+    record?: LocationRecord;
+};
+type LocationRecordSigner = {
+    type: "did:pkh";
+    signMessage(message: string): Promise<string>;
+} | {
+    type: "did:key";
+    signBytes(bytes: Uint8Array): Promise<Uint8Array>;
+};
+declare class LocationRecordValidationError extends Error {
+    constructor(message: string);
+}
+declare class CloudLocationResolutionError extends Error {
+    readonly attempts: LocationResolutionAttempt[];
+    constructor(subject: string, attempts: LocationResolutionAttempt[]);
+}
+declare function locationPayloadForRecord(record: LocationRecord): LocationRecordPayload;
+declare function canonicalLocationPayload(payload: LocationRecordPayload): string;
+declare function signLocationRecord(payload: LocationRecordPayload, signer: LocationRecordSigner): Promise<LocationRecord>;
+declare function validateLocationRecordPayload(input: unknown): LocationRecordPayload;
+declare function validateLocationRecord(input: unknown): LocationRecord;
+declare function verifyLocationRecord(input: LocationRecord): Promise<boolean>;
+declare function fetchLocationRecord(registryUrl: string, subject: string, fetchFn?: typeof fetch): Promise<LocationRecord | null>;
+declare function resolveCloudLocation(subject: string, options?: ResolveCloudLocationOptions): Promise<ResolvedCloudLocation>;
+declare function resolveTinyCloudHosts(subject: string, options?: ResolveTinyCloudHostsOptions): Promise<ResolvedTinyCloudHosts>;
+declare function multiaddrToHttpUrl(input: string): string;
+declare function httpUrlToMultiaddr(input: string): string;
+
+export { ACCOUNT_REGISTRY_PATH, ACCOUNT_REGISTRY_SPACE, type AbilitiesMap, AutoApproveSpaceCreationHandler, type AutoRejectStrategy, type AutoSignStrategy, type Bytes, type CallbackStrategy, type CapabilityEntry, CapabilityKeyRegistry, type CapabilityKeyRegistryErrorCode, CapabilityKeyRegistryErrorCodes, type ClientSession, ClientSessionSchema, CloudLocationResolutionError, type ComposeManifestOptions, type ComposedManifestRequest, type CreateDelegationFunction, type CreateDelegationParams, type CreateDelegationWasmParams, type CreateDelegationWasmResult, DEFAULT_DEFAULTS, DEFAULT_EXPIRY, DEFAULT_MANIFEST_SPACE, DEFAULT_MANIFEST_VERSION, DEFAULT_TINYCLOUD_FALLBACK_HOST, DEFAULT_TINYCLOUD_LOCATION_REGISTRY_URL, type DelegatedResource, type Delegation, type DelegationApiResponse, type DelegationChain, type DelegationChainV2, type DelegationDirection, type DelegationError, type DelegationErrorCode, DelegationErrorCodes, type DelegationFilters, DelegationManager, type DelegationManagerConfig, type DelegationRecord, type Result as DelegationResult, type EncodedShareData, type EnsData, EnsDataSchema, type EventEmitterStrategy, type Extension, type GenerateShareParams, type ICapabilityKeyRegistry, type IENSResolver, type INotificationHandler, type ISessionManager, type ISessionStorage, type ISharingService, type ISigner, type ISpace, type ISpaceCreationHandler, type ISpaceScopedDelegations, type ISpaceScopedSharing, type ISpaceService, type IUserAuthorization, type IWasmBindings, type IngestOptions, type JWK, type KeyInfo, type KeyProvider, type KeyType, type LocationCandidate, type LocationCandidateInput, type LocationRecord, type LocationRecordPayload, type LocationRecordSigner, LocationRecordValidationError, type LocationResolutionAttempt, type LocationSource, type Manifest, type ManifestDefaults, type ManifestRegistryRecord, ManifestValidationError, type NodeInfo, type ParseRecapFromSiwe, type PartialSiweMessage, type PermissionEntry, PermissionNotInManifestError, type PersistedSessionData, type PersistedTinyCloudSession, ProtocolMismatchError, type ReceiveOptions, type ResolveCloudLocationOptions, type ResolveTinyCloudHostsOptions, type ResolvedCapabilities, type ResolvedCloudLocation, type ResolvedDelegate, type ResolvedTinyCloudHosts, type ResourceCapability, SERVICE_LONG_TO_SHORT, SERVICE_SHORT_TO_LONG, type ServerHost, SessionExpiredError, type ShareAccess, type ShareLink, type ShareLinkData, type ShareSchema, SharingService, type SharingServiceConfig, type SignCallback, type SignInOptions, type SignRequest, type SignResponse, type SignStrategy, SilentNotificationHandler, type SiweConfig, SiweConfigSchema, Space, type SpaceAbilitiesMap, type SpaceConfig, type SpaceCreationContext, type SpaceDelegationParams, type SpaceErrorCode, SpaceErrorCodes, type SpaceHostResult, type SpaceInfo, type SpaceOwnership, SpaceService, type SpaceServiceConfig, type StoredDelegationChain, type SubsetCheckResult, TinyCloud, type TinyCloudConfig, type TinyCloudSession, UnsupportedFeatureError, type UserAuthorizationConfig, type ValidationError, VersionCheckError, type WasmRecapEntry, activateSessionWithHost, applyPrefix, buildSpaceUri, canonicalLocationPayload, checkNodeInfo, composeManifestRequest, createCapabilityKeyRegistry, createSharingService, createSpaceService, defaultSignStrategy, defaultSpaceCreationHandler, expandActionShortNames, fetchLocationRecord, fetchPeerId, httpUrlToMultiaddr, isCapabilitySubset, loadManifest, locationPayloadForRecord, makePublicSpaceId, manifestAbilitiesUnion, multiaddrToHttpUrl, normalizeDefaults, parseExpiry, parseRecapCapabilities, parseSpaceUri, resolveCloudLocation, resolveManifest, resolveTinyCloudHosts, resourceCapabilitiesToAbilitiesMap, resourceCapabilitiesToSpaceAbilitiesMap, signLocationRecord, submitHostDelegation, validateClientSession, validateLocationRecord, validateLocationRecordPayload, validateManifest, validatePersistedSessionData, verifyLocationRecord };

package/dist/index.js

@@ -4250,6 +4250,394 @@ async function checkNodeInfo(host, sdkProtocol, fetchFn = globalThis.fetch.bind(
   };
 }
 
+// src/location.ts
+import { multiaddr } from "@multiformats/multiaddr";
+import { multiaddrToUri } from "@multiformats/multiaddr-to-uri";
+import { uriToMultiaddr } from "@multiformats/uri-to-multiaddr";
+import { ed25519 } from "@noble/curves/ed25519";
+import { bases } from "multiformats/basics";
+import { verifyMessage } from "viem";
+var DEFAULT_TINYCLOUD_LOCATION_REGISTRY_URL = "https://registry.tinycloud.xyz";
+var DEFAULT_TINYCLOUD_FALLBACK_HOST = "https://node.tinycloud.xyz";
+var LocationRecordValidationError = class extends Error {
+  constructor(message) {
+    super(`Location record validation failed: ${message}`);
+    this.name = "LocationRecordValidationError";
+  }
+};
+var CloudLocationResolutionError = class extends Error {
+  constructor(subject, attempts) {
+    super(`Unable to resolve TinyCloud location for ${subject}`);
+    this.name = "CloudLocationResolutionError";
+    this.attempts = attempts;
+  }
+};
+function locationPayloadForRecord(record) {
+  return {
+    version: record.version,
+    subject: record.subject,
+    multiaddrs: [...record.multiaddrs],
+    updated_at: record.updated_at,
+    sequence: record.sequence
+  };
+}
+function canonicalLocationPayload(payload) {
+  return JSON.stringify({
+    version: payload.version,
+    subject: payload.subject,
+    multiaddrs: payload.multiaddrs,
+    updated_at: payload.updated_at,
+    sequence: payload.sequence
+  });
+}
+async function signLocationRecord(payload, signer) {
+  validateLocationRecordPayload(payload);
+  const message = canonicalLocationPayload(payload);
+  const signature = signer.type === "did:pkh" ? await signer.signMessage(message) : base64UrlEncode2(
+    await signer.signBytes(new TextEncoder().encode(message))
+  );
+  return { ...payload, signature };
+}
+function validateLocationRecordPayload(input) {
+  if (input === null || typeof input !== "object") {
+    throw new LocationRecordValidationError("payload must be an object");
+  }
+  const payload = input;
+  if (payload.version !== 1) {
+    throw new LocationRecordValidationError("version must be 1");
+  }
+  validateSubject(payload.subject);
+  validateMultiaddrs(payload.multiaddrs);
+  if (typeof payload.updated_at !== "string" || Number.isNaN(Date.parse(payload.updated_at))) {
+    throw new LocationRecordValidationError(
+      "updated_at must be an ISO timestamp"
+    );
+  }
+  if (typeof payload.sequence !== "number" || !Number.isSafeInteger(payload.sequence) || payload.sequence < 0) {
+    throw new LocationRecordValidationError(
+      "sequence must be a non-negative safe integer"
+    );
+  }
+  return {
+    version: 1,
+    subject: payload.subject,
+    multiaddrs: [...payload.multiaddrs],
+    updated_at: payload.updated_at,
+    sequence: payload.sequence
+  };
+}
+function validateLocationRecord(input) {
+  const payload = validateLocationRecordPayload(input);
+  const signature = input.signature;
+  if (typeof signature !== "string" || signature.length === 0) {
+    throw new LocationRecordValidationError(
+      "signature must be a non-empty string"
+    );
+  }
+  return { ...payload, signature };
+}
+async function verifyLocationRecord(input) {
+  const record = validateLocationRecord(input);
+  const payload = canonicalLocationPayload(locationPayloadForRecord(record));
+  if (record.subject.startsWith("did:pkh:")) {
+    return verifyPkhSignature(record.subject, payload, record.signature);
+  }
+  if (record.subject.startsWith("did:key:")) {
+    return verifyDidKeySignature(record.subject, payload, record.signature);
+  }
+  return false;
+}
+async function fetchLocationRecord(registryUrl, subject, fetchFn = globalThis.fetch) {
+  const url = `${registryUrl.replace(/\/$/, "")}/v1/locations/${encodeURIComponent(subject)}`;
+  const response = await fetchFn(url);
+  if (response.status === 404) {
+    return null;
+  }
+  if (!response.ok) {
+    throw new Error(`location registry returned HTTP ${response.status}`);
+  }
+  const body = await response.json();
+  if (body.record === void 0) {
+    throw new LocationRecordValidationError("registry response missing record");
+  }
+  return validateLocationRecord(body.record);
+}
+async function resolveCloudLocation(subject, options = {}) {
+  validateSubject(subject);
+  const verifyRecords = options.verifyRecords ?? true;
+  const attempts = await Promise.all([
+    resolveExplicit(subject, options.explicitMultiaddrs),
+    resolveBlockchain(subject, options.blockchain, verifyRecords),
+    resolveCentralized(subject, options, verifyRecords),
+    resolveFallback(subject, options.fallbackMultiaddrs)
+  ]);
+  const winner = attempts.find((attempt) => attempt.candidate)?.candidate;
+  if (!winner) {
+    throw new CloudLocationResolutionError(subject, attempts);
+  }
+  return {
+    subject,
+    source: winner.source,
+    multiaddrs: [...winner.multiaddrs],
+    ...winner.record ? { record: winner.record } : {},
+    attempts,
+    resolvedAt: (/* @__PURE__ */ new Date()).toISOString()
+  };
+}
+async function resolveTinyCloudHosts(subject, options = {}) {
+  const location = await resolveCloudLocation(subject, {
+    explicitMultiaddrs: hostsToMultiaddrs(options.explicitHosts),
+    blockchain: options.blockchain,
+    centralizedRegistryUrl: options.registryUrl === null ? void 0 : options.registryUrl ?? DEFAULT_TINYCLOUD_LOCATION_REGISTRY_URL,
+    fallbackMultiaddrs: hostsToMultiaddrs(
+      options.fallbackHosts === null ? void 0 : options.fallbackHosts ?? [DEFAULT_TINYCLOUD_FALLBACK_HOST]
+    ),
+    fetch: options.fetch,
+    verifyRecords: options.verifyRecords
+  });
+  return {
+    hosts: location.multiaddrs.map((addr) => multiaddrToHttpUrl(addr)),
+    location
+  };
+}
+function multiaddrToHttpUrl(input) {
+  const uri = multiaddrToUri(multiaddr(input));
+  if (!uri.startsWith("http://") && !uri.startsWith("https://")) {
+    throw new LocationRecordValidationError(
+      `multiaddr does not resolve to http/https: ${input}`
+    );
+  }
+  return uri;
+}
+function httpUrlToMultiaddr(input) {
+  const url = new URL(input);
+  if (url.protocol !== "http:" && url.protocol !== "https:") {
+    throw new LocationRecordValidationError("URL must use http or https");
+  }
+  return uriToMultiaddr(url.toString()).toString();
+}
+function hostsToMultiaddrs(hosts) {
+  if (hosts === void 0 || hosts.length === 0) {
+    return void 0;
+  }
+  return hosts.map(
+    (host) => host.startsWith("/") ? host : httpUrlToMultiaddr(host)
+  );
+}
+async function resolveExplicit(subject, multiaddrs) {
+  return resolveAttempt("explicit", async () => {
+    if (multiaddrs === void 0 || multiaddrs.length === 0) {
+      return null;
+    }
+    return toCandidate(subject, "explicit", multiaddrs, false);
+  });
+}
+async function resolveBlockchain(subject, resolver, verifyRecords) {
+  return resolveAttempt("blockchain", async () => {
+    if (!resolver) {
+      return null;
+    }
+    return toCandidate(
+      subject,
+      "blockchain",
+      await resolver(subject),
+      verifyRecords
+    );
+  });
+}
+async function resolveCentralized(subject, options, verifyRecords) {
+  return resolveAttempt("centralized", async () => {
+    if (!options.centralizedRegistryUrl) {
+      return null;
+    }
+    const record = await fetchLocationRecord(
+      options.centralizedRegistryUrl,
+      subject,
+      options.fetch
+    );
+    return toCandidate(subject, "centralized", record, verifyRecords);
+  });
+}
+async function resolveFallback(subject, multiaddrs) {
+  return resolveAttempt("fallback", async () => {
+    if (multiaddrs === void 0 || multiaddrs.length === 0) {
+      return null;
+    }
+    return toCandidate(subject, "fallback", multiaddrs, false);
+  });
+}
+async function resolveAttempt(source, resolve) {
+  try {
+    const candidate = await resolve();
+    return candidate ? { source, candidate } : { source };
+  } catch (error) {
+    return {
+      source,
+      error: error instanceof Error ? error : new Error(String(error))
+    };
+  }
+}
+async function toCandidate(subject, source, input, verifyRecord) {
+  if (input === null || input === void 0) {
+    return null;
+  }
+  if (Array.isArray(input)) {
+    validateMultiaddrs(input);
+    return { source, multiaddrs: [...input] };
+  }
+  const maybeRecord = input;
+  if (maybeRecord.version === 1 && maybeRecord.signature !== void 0) {
+    const record = validateLocationRecord(input);
+    if (record.subject !== subject) {
+      throw new LocationRecordValidationError(
+        "location record subject does not match requested subject"
+      );
+    }
+    if (verifyRecord && !await verifyLocationRecord(record)) {
+      throw new LocationRecordValidationError(
+        "location record signature is invalid"
+      );
+    }
+    return { source, multiaddrs: [...record.multiaddrs], record };
+  }
+  const candidateInput = input;
+  if (!Array.isArray(candidateInput.multiaddrs)) {
+    throw new LocationRecordValidationError(
+      "candidate multiaddrs must be an array"
+    );
+  }
+  validateMultiaddrs(candidateInput.multiaddrs);
+  if (candidateInput.record !== void 0) {
+    const record = validateLocationRecord(candidateInput.record);
+    if (record.subject !== subject) {
+      throw new LocationRecordValidationError(
+        "location record subject does not match requested subject"
+      );
+    }
+    if (verifyRecord && !await verifyLocationRecord(record)) {
+      throw new LocationRecordValidationError(
+        "location record signature is invalid"
+      );
+    }
+    return { source, multiaddrs: [...candidateInput.multiaddrs], record };
+  }
+  return { source, multiaddrs: [...candidateInput.multiaddrs] };
+}
+function validateSubject(subject) {
+  if (typeof subject !== "string" || subject.length === 0) {
+    throw new LocationRecordValidationError(
+      "subject must be a non-empty string"
+    );
+  }
+  if (!subject.startsWith("did:pkh:") && !subject.startsWith("did:key:")) {
+    throw new LocationRecordValidationError(
+      "subject must be did:pkh or did:key"
+    );
+  }
+}
+function validateMultiaddrs(input) {
+  if (!Array.isArray(input)) {
+    throw new LocationRecordValidationError("multiaddrs must be an array");
+  }
+  for (const addr of input) {
+    if (typeof addr !== "string" || addr.length === 0) {
+      throw new LocationRecordValidationError(
+        "multiaddr entries must be non-empty strings"
+      );
+    }
+    try {
+      multiaddr(addr);
+    } catch {
+      throw new LocationRecordValidationError(`invalid multiaddr: ${addr}`);
+    }
+  }
+}
+async function verifyPkhSignature(did, payload, signature) {
+  const address = did.split(":").at(-1);
+  if (!address || !/^0x[a-fA-F0-9]{40}$/.test(address)) {
+    throw new LocationRecordValidationError(
+      "did:pkh subject must end with an EVM address"
+    );
+  }
+  if (!/^0x[0-9a-fA-F]+$/.test(signature)) {
+    throw new LocationRecordValidationError("did:pkh signature must be hex");
+  }
+  return verifyMessage({
+    address,
+    message: payload,
+    signature
+  });
+}
+function verifyDidKeySignature(did, payload, signature) {
+  const publicKey = ed25519PublicKeyFromDidKey(did);
+  const signatureBytes = decodeBase64Url(signature);
+  if (signatureBytes.length !== 64) {
+    throw new LocationRecordValidationError(
+      "did:key signature must be a base64url Ed25519 signature"
+    );
+  }
+  return ed25519.verify(
+    signatureBytes,
+    new TextEncoder().encode(payload),
+    publicKey
+  );
+}
+function ed25519PublicKeyFromDidKey(did) {
+  const identifier = did.slice("did:key:".length);
+  if (!identifier.startsWith("z")) {
+    throw new LocationRecordValidationError(
+      "did:key must use base58btc multibase"
+    );
+  }
+  const bytes = bases.base58btc.decode(identifier);
+  if (bytes.length !== 34 || bytes[0] !== 237 || bytes[1] !== 1) {
+    throw new LocationRecordValidationError(
+      "did:key must be an Ed25519 public key"
+    );
+  }
+  return bytes.slice(2);
+}
+function base64UrlEncode2(bytes) {
+  const alphabet = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_";
+  let output = "";
+  for (let i = 0; i < bytes.length; i += 3) {
+    const a = bytes[i];
+    const b = bytes[i + 1];
+    const c = bytes[i + 2];
+    const triplet = a << 16 | (b ?? 0) << 8 | (c ?? 0);
+    output += alphabet[triplet >> 18 & 63];
+    output += alphabet[triplet >> 12 & 63];
+    if (i + 1 < bytes.length) {
+      output += alphabet[triplet >> 6 & 63];
+    }
+    if (i + 2 < bytes.length) {
+      output += alphabet[triplet & 63];
+    }
+  }
+  return output;
+}
+function decodeBase64Url(value) {
+  const alphabet = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_";
+  const bytes = [];
+  let buffer = 0;
+  let bits = 0;
+  for (const char of value) {
+    const index = alphabet.indexOf(char);
+    if (index < 0) {
+      throw new LocationRecordValidationError(
+        "did:key signature must be base64url"
+      );
+    }
+    buffer = buffer << 6 | index;
+    bits += 6;
+    if (bits >= 8) {
+      bits -= 8;
+      bytes.push(buffer >> bits & 255);
+    }
+  }
+  return Uint8Array.from(bytes);
+}
+
 // src/capabilities.ts
 var PermissionNotInManifestError = class extends Error {
   constructor(missing, granted) {
@@ -4370,10 +4758,13 @@ export {
   CapabilityKeyRegistry,
   CapabilityKeyRegistryErrorCodes,
   ClientSessionSchema,
+  CloudLocationResolutionError,
   DEFAULT_DEFAULTS,
   DEFAULT_EXPIRY,
   DEFAULT_MANIFEST_SPACE,
   DEFAULT_MANIFEST_VERSION,
+  DEFAULT_TINYCLOUD_FALLBACK_HOST,
+  DEFAULT_TINYCLOUD_LOCATION_REGISTRY_URL,
   DataVaultService,
   DatabaseHandle,
   DelegationErrorCodes,
@@ -4385,6 +4776,7 @@ export {
   ErrorCodes2 as ErrorCodes,
   HooksService2 as HooksService,
   KVService2 as KVService,
+  LocationRecordValidationError,
   ManifestValidationError,
   PermissionNotInManifestError,
   PrefixedKVService,
@@ -4410,6 +4802,7 @@ export {
   activateSessionWithHost,
   applyPrefix,
   buildSpaceUri,
+  canonicalLocationPayload,
   checkNodeInfo,
   composeManifestRequest,
   createCapabilityKeyRegistry,
@@ -4421,23 +4814,33 @@ export {
   defaultSpaceCreationHandler,
   err4 as err,
   expandActionShortNames,
+  fetchLocationRecord,
   fetchPeerId,
+  httpUrlToMultiaddr,
   isCapabilitySubset,
   loadManifest,
+  locationPayloadForRecord,
   makePublicSpaceId,
   manifestAbilitiesUnion,
+  multiaddrToHttpUrl,
   normalizeDefaults,
   ok4 as ok,
   parseExpiry,
   parseRecapCapabilities,
   parseSpaceUri,
+  resolveCloudLocation,
   resolveManifest,
+  resolveTinyCloudHosts,
   resourceCapabilitiesToAbilitiesMap,
   resourceCapabilitiesToSpaceAbilitiesMap,
   serviceError4 as serviceError,
+  signLocationRecord,
   submitHostDelegation,
   validateClientSession,
+  validateLocationRecord,
+  validateLocationRecordPayload,
   validateManifest,
-  validatePersistedSessionData
+  validatePersistedSessionData,
+  verifyLocationRecord
 };
 //# sourceMappingURL=index.js.map