@tinycloud/sdk-core 2.8.0 → 2.9.0-beta.0

package/dist/index.d.cts

@@ -5331,9 +5331,25 @@ interface LocationRecordPayload {
 interface LocationRecord extends LocationRecordPayload {
     signature: string;
 }
-type LocationSource = "explicit" | "blockchain" | "centralized" | "fallback";
+/**
+ * Where a resolved TinyCloud host came from, ordered highest to lowest
+ * priority. `local-loopback` and `local-link` are probed + identity-verified
+ * (see {@link discoverLocalTinyCloudNode}); the rest are resolved the same
+ * way they always have been (no liveness probing). New local-discovery
+ * sources (e.g. a future `tunnel` or `mdns` source) slot in next to
+ * `local-link` without touching the unprobed sources below them.
+ */
+type LocationSource = "explicit" | "local-loopback" | "local-link" | "blockchain" | "centralized" | "fallback";
 declare const DEFAULT_TINYCLOUD_LOCATION_REGISTRY_URL = "https://registry.tinycloud.xyz";
 declare const DEFAULT_TINYCLOUD_FALLBACK_HOST = "https://node.tinycloud.xyz";
+/** Default local loopback node URL probed before registry/fallback resolution. */
+declare const DEFAULT_LOCAL_NODE_URL = "http://127.0.0.1:8000";
+/** Probe timeout for the local loopback candidate. No retries. */
+declare const LOCAL_LOOPBACK_PROBE_TIMEOUT_MS = 250;
+/** Probe timeout for local.tinycloud.link candidates. No retries. */
+declare const LOCAL_LINK_PROBE_TIMEOUT_MS = 750;
+/** Hostname suffix identifying a local-link tunnel candidate. */
+declare const LOCAL_LINK_HOST_SUFFIX = ".local.tinycloud.link";
 interface LocationCandidate {
     source: LocationSource;
     multiaddrs: string[];
@@ -5370,6 +5386,69 @@ interface ResolvedTinyCloudHosts {
     hosts: string[];
     location: ResolvedCloudLocation;
 }
+/**
+ * Trust-on-first-use pin store for locally-discovered node identities, keyed
+ * by candidate URL. The first successful `/info` check for a URL with no
+ * existing pin adopts and pins that node's DID; every later check for the
+ * same URL must match the pin. Implementations: CLI (profile store), web
+ * (localStorage), node-sdk (config-provided callback, else in-memory).
+ */
+interface LocalNodeIdentityStore {
+    get(url: string): string | undefined | Promise<string | undefined>;
+    set(url: string, nodeDid: string): void | Promise<void>;
+}
+/** In-memory {@link LocalNodeIdentityStore}. Does not persist across process restarts. */
+declare function createInMemoryLocalNodeIdentityStore(): LocalNodeIdentityStore;
+/**
+ * Minimal subset of the DOM `Storage` interface. Declared locally so
+ * sdk-core (no DOM lib) doesn't need to depend on browser types.
+ */
+interface WebStorageLike {
+    getItem(key: string): string | null;
+    setItem(key: string, value: string): void;
+    removeItem(key: string): void;
+}
+/** Default namespaced key {@link createLocalStorageLocalNodeIdentityStore} stores its pins under. */
+declare const DEFAULT_LOCAL_NODE_PIN_STORAGE_KEY = "tinycloud.localNodePins.v1";
+/**
+ * `localStorage`-backed {@link LocalNodeIdentityStore}, namespaced under a
+ * single JSON blob (default key {@link DEFAULT_LOCAL_NODE_PIN_STORAGE_KEY}).
+ * Falls back to an in-memory store when `localStorage` is unavailable (SSR,
+ * Node.js, sandboxed contexts that throw on access, etc.), so callers never
+ * have to branch on environment. Corrupt stored JSON is reset rather than
+ * thrown.
+ */
+declare function createLocalStorageLocalNodeIdentityStore(storage?: WebStorageLike, storageKey?: string): LocalNodeIdentityStore;
+interface DiscoverLocalTinyCloudNodeOptions {
+    /**
+     * Subject DID used to look up the registry LocationRecord for
+     * `*.local.tinycloud.link` multiaddrs (source `local-link`). Omit to skip
+     * that lookup — the local-loopback and `localLinkName` candidates don't
+     * need it.
+     */
+    subject?: string;
+    /** Enable local-node auto-discovery. Default true. */
+    autoDiscoverLocalNode?: boolean;
+    /** Local loopback node URL to probe. Default http://127.0.0.1:8000. */
+    localNodeUrl?: string;
+    /** Known `*.local.tinycloud.link` subdomain name, probed directly. */
+    localLinkName?: string;
+    /** Centralized location registry URL, used for the `local-link` registry lookup. Default https://registry.tinycloud.xyz. */
+    registryUrl?: string | null;
+    /** Expected local node DID. Wins over any pinned value; a mismatch rejects the candidate. */
+    expectedNodeDid?: string;
+    /** Pin store for trust-on-first-use identity verification. Defaults to an in-memory store. */
+    identityStore?: LocalNodeIdentityStore;
+    /** Verify the registry LocationRecord signature before trusting its `local-link` multiaddrs. Default true. */
+    verifyRecords?: boolean;
+    /** Custom fetch implementation. Defaults to globalThis.fetch. */
+    fetch?: typeof fetch;
+}
+interface DiscoveredLocalTinyCloudNode {
+    source: Extract<LocationSource, "local-loopback" | "local-link">;
+    url: string;
+    nodeDid: string;
+}
 interface ResolveTinyCloudHostsOptions {
     /** Highest-priority TinyCloud HTTP host URLs or multiaddrs supplied directly. */
     explicitHosts?: string[];
@@ -5383,6 +5462,20 @@ interface ResolveTinyCloudHostsOptions {
     fetch?: typeof fetch;
     /** Verify centralized/blockchain record signatures. Default true. */
     verifyRecords?: boolean;
+    /**
+     * Probe for a locally-running TinyCloud node before falling back to
+     * registry/hosted resolution. Default true. Setting false restores the
+     * exact pre-TC-106 resolution order (registry → fallback).
+     */
+    autoDiscoverLocalNode?: boolean;
+    /** Local loopback node URL to probe. Default http://127.0.0.1:8000. */
+    localNodeUrl?: string;
+    /** Known `*.local.tinycloud.link` subdomain name, probed directly. */
+    localLinkName?: string;
+    /** Expected local node DID. Wins over any pinned value; a mismatch rejects the candidate. */
+    expectedNodeDid?: string;
+    /** Pin store for trust-on-first-use local node identity verification. Defaults to an in-memory store. */
+    localNodeIdentityStore?: LocalNodeIdentityStore;
 }
 type LocationCandidateInput = string[] | LocationRecord | {
     multiaddrs: string[];
@@ -5411,6 +5504,23 @@ 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>;
+/**
+ * Probe for a locally-running TinyCloud node and verify its identity before
+ * trusting it. Tries, in order: the local loopback URL, the explicit
+ * `localLinkName` candidate (if given), then any `*.local.tinycloud.link`
+ * multiaddr found in the subject's registry LocationRecord (if `subject` and
+ * a registry are given). Each candidate is probed with `GET {url}/healthz`
+ * (short timeout, no retries) — any failure (refused, timeout, NXDOMAIN,
+ * offline) silently skips to the next candidate, no error, no log above
+ * debug level. A candidate that answers healthy is then identity-checked via
+ * `GET {url}/info`: if an expected DID is known (explicit or previously
+ * pinned), the node's `nodeId` DID must match or the candidate is rejected;
+ * if no expectation exists yet, the DID is trusted and pinned (TOFU).
+ *
+ * Returns `null` (never throws) when no local node is found or verified —
+ * callers fall through to their normal remote resolution.
+ */
+declare function discoverLocalTinyCloudNode(options?: DiscoverLocalTinyCloudNodeOptions): Promise<DiscoveredLocalTinyCloudNode | null>;
 declare function multiaddrToHttpUrl(input: string): string;
 declare function httpUrlToMultiaddr(input: string): string;
 declare function verifyDidKeyEd25519Signature(did: string, payload: Uint8Array, signature: Uint8Array): boolean;
@@ -5444,4 +5554,4 @@ declare const EXPIRY: {
 declare const DEFAULT_SIGNED_READ_URL_EXPIRY_MS: number;
 type ExpiryTier = keyof typeof EXPIRY;
 
-export { ACCOUNT_REGISTRY_PATH, ACCOUNT_REGISTRY_SPACE, type AbilitiesMap, type AccountApplication, type AccountApplicationListOptions, type AccountDelegation, type AccountDelegationListOptions, type AccountDelegationPage, type AccountDelegationQueryOptions, type AccountDelegationRecord, type AccountDelegationResource, type AccountDelegationRevokeOptions, type AccountIndexEnsureResult, type AccountIndexRebuildResult, type AccountIndexStatus, type AccountIndexedReadOptions, AccountService, type AccountServiceConfig, type AccountSpace, type AccountSpaceListOptions, type AccountStatus, AutoApproveSpaceCreationHandler, type AutoRejectStrategy, type AutoSignStrategy, type Bytes, type CallbackStrategy, type CanonicalAddress, type CanonicalParsedNetworkId, type CapabilityEntry, CapabilityKeyRegistry, type CapabilityKeyRegistryErrorCode, CapabilityKeyRegistryErrorCodes, CaveatedDelegationUnsupportedError, type ClientSession, ClientSessionSchema, CloudLocationResolutionError, type ComposeManifestOptions, type ComposedManifestRequest, type CreateDelegationFunction, type CreateDelegationParams, type CreateDelegationWasmParams, type CreateDelegationWasmResult, DEFAULT_DEFAULTS, DEFAULT_EXPIRY, DEFAULT_KNOWLEDGE_ROOT, DEFAULT_MANIFEST_SPACE, DEFAULT_MANIFEST_VERSION, DEFAULT_SIGNED_READ_URL_EXPIRY_MS, DEFAULT_TINYCLOUD_FALLBACK_HOST, DEFAULT_TINYCLOUD_LOCATION_REGISTRY_URL, type DelegateReceivedShareParams, type DelegatedResource, type DelegatedShareAccess, 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 DelegationRevocationReceipt, type DelegationStatus, type DidCacheKeyOptions, type DidEqualsOptions, ENCRYPTION_MANIFEST_SPACE, ENCRYPTION_PERMISSION_SERVICE, EXPIRY, type EncodedShareData, type EnsData, EnsDataSchema, type EventEmitterStrategy, type ExpiryTier, 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, IdentityParseError, 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 ManifestKnowledge, type ManifestRegistryRecord, type ManifestSecretActions, ManifestValidationError, type NodeInfo, type OpenKeyCallbackStrategy, type OpenKeySigningRequestBody, type OpenKeySigningResponseBody, type OpenKeySigningStrategyOptions, type ParseRecapFromSiwe, type PartialSiweMessage, type PermissionEntry, PermissionNotInManifestError, type PersistedSessionData, type PersistedSessionProof, type PersistedTinyCloudSession, type PkhDidParts, ProtocolMismatchError, type ReceiveOptions, type ResolveCloudLocationOptions, type ResolveTinyCloudHostsOptions, type ResolvedCapabilities, type ResolvedCloudLocation, type ResolvedDelegate, type ResolvedTinyCloudHosts, type ResourceCapability, SECRETS_SPACE, 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, VAULT_PERMISSION_SERVICE, type ValidatedPersistedSessionProof, type ValidationError, VersionCheckError, type WasmRecapEntry, actionContains, activateSessionWithHost, addressStorageKey, applyPrefix, buildSpaceUri, canonicalLocationPayload, canonicalizeAddress, canonicalizeDid, canonicalizeDidUrl, canonicalizeNetworkId, canonicalizeRecapCaveats, checkNodeInfo, composeManifestRequest, createCapabilityKeyRegistry, createOpenKeyCallbackSigningStrategy, createSharingService, createSpaceService, defaultSignStrategy, defaultSpaceCreationHandler, didCacheKey, didEquals, expandActionShortNames, expandPermissionEntries, expandPermissionEntry, fetchLocationRecord, fetchPeerId, httpUrlToMultiaddr, isCapabilitySubset, isEvmAddress, loadManifest, locationPayloadForRecord, makePkhSpaceId, makePublicSpaceId, manifestAbilitiesUnion, multiaddrToHttpUrl, normalizeDefaults, parseCanonicalNetworkId, parseExpiry, parsePkhDid, parseRecapCapabilities, parseSpaceUri, pkhDid, principalDid, principalDidEquals, recapCaveatsEqual, resolveCloudLocation, resolveManifest, resolveManifestKnowledgeRoot, resolveTinyCloudHosts, resourceCapabilitiesToAbilitiesMap, resourceCapabilitiesToSpaceAbilitiesMap, signLocationRecord, submitHostDelegation, validateClientSession, validateLocationRecord, validateLocationRecordPayload, validateManifest, validatePersistedSessionData, verifyDidKeyEd25519Signature, verifyLocationRecord };
+export { ACCOUNT_REGISTRY_PATH, ACCOUNT_REGISTRY_SPACE, type AbilitiesMap, type AccountApplication, type AccountApplicationListOptions, type AccountDelegation, type AccountDelegationListOptions, type AccountDelegationPage, type AccountDelegationQueryOptions, type AccountDelegationRecord, type AccountDelegationResource, type AccountDelegationRevokeOptions, type AccountIndexEnsureResult, type AccountIndexRebuildResult, type AccountIndexStatus, type AccountIndexedReadOptions, AccountService, type AccountServiceConfig, type AccountSpace, type AccountSpaceListOptions, type AccountStatus, AutoApproveSpaceCreationHandler, type AutoRejectStrategy, type AutoSignStrategy, type Bytes, type CallbackStrategy, type CanonicalAddress, type CanonicalParsedNetworkId, type CapabilityEntry, CapabilityKeyRegistry, type CapabilityKeyRegistryErrorCode, CapabilityKeyRegistryErrorCodes, CaveatedDelegationUnsupportedError, type ClientSession, ClientSessionSchema, CloudLocationResolutionError, type ComposeManifestOptions, type ComposedManifestRequest, type CreateDelegationFunction, type CreateDelegationParams, type CreateDelegationWasmParams, type CreateDelegationWasmResult, DEFAULT_DEFAULTS, DEFAULT_EXPIRY, DEFAULT_KNOWLEDGE_ROOT, DEFAULT_LOCAL_NODE_PIN_STORAGE_KEY, DEFAULT_LOCAL_NODE_URL, DEFAULT_MANIFEST_SPACE, DEFAULT_MANIFEST_VERSION, DEFAULT_SIGNED_READ_URL_EXPIRY_MS, DEFAULT_TINYCLOUD_FALLBACK_HOST, DEFAULT_TINYCLOUD_LOCATION_REGISTRY_URL, type DelegateReceivedShareParams, type DelegatedResource, type DelegatedShareAccess, 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 DelegationRevocationReceipt, type DelegationStatus, type DidCacheKeyOptions, type DidEqualsOptions, type DiscoverLocalTinyCloudNodeOptions, type DiscoveredLocalTinyCloudNode, ENCRYPTION_MANIFEST_SPACE, ENCRYPTION_PERMISSION_SERVICE, EXPIRY, type EncodedShareData, type EnsData, EnsDataSchema, type EventEmitterStrategy, type ExpiryTier, 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, IdentityParseError, type IngestOptions, type JWK, type KeyInfo, type KeyProvider, type KeyType, LOCAL_LINK_HOST_SUFFIX, LOCAL_LINK_PROBE_TIMEOUT_MS, LOCAL_LOOPBACK_PROBE_TIMEOUT_MS, type LocalNodeIdentityStore, type LocationCandidate, type LocationCandidateInput, type LocationRecord, type LocationRecordPayload, type LocationRecordSigner, LocationRecordValidationError, type LocationResolutionAttempt, type LocationSource, type Manifest, type ManifestDefaults, type ManifestKnowledge, type ManifestRegistryRecord, type ManifestSecretActions, ManifestValidationError, type NodeInfo, type OpenKeyCallbackStrategy, type OpenKeySigningRequestBody, type OpenKeySigningResponseBody, type OpenKeySigningStrategyOptions, type ParseRecapFromSiwe, type PartialSiweMessage, type PermissionEntry, PermissionNotInManifestError, type PersistedSessionData, type PersistedSessionProof, type PersistedTinyCloudSession, type PkhDidParts, ProtocolMismatchError, type ReceiveOptions, type ResolveCloudLocationOptions, type ResolveTinyCloudHostsOptions, type ResolvedCapabilities, type ResolvedCloudLocation, type ResolvedDelegate, type ResolvedTinyCloudHosts, type ResourceCapability, SECRETS_SPACE, 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, VAULT_PERMISSION_SERVICE, type ValidatedPersistedSessionProof, type ValidationError, VersionCheckError, type WasmRecapEntry, type WebStorageLike, actionContains, activateSessionWithHost, addressStorageKey, applyPrefix, buildSpaceUri, canonicalLocationPayload, canonicalizeAddress, canonicalizeDid, canonicalizeDidUrl, canonicalizeNetworkId, canonicalizeRecapCaveats, checkNodeInfo, composeManifestRequest, createCapabilityKeyRegistry, createInMemoryLocalNodeIdentityStore, createLocalStorageLocalNodeIdentityStore, createOpenKeyCallbackSigningStrategy, createSharingService, createSpaceService, defaultSignStrategy, defaultSpaceCreationHandler, didCacheKey, didEquals, discoverLocalTinyCloudNode, expandActionShortNames, expandPermissionEntries, expandPermissionEntry, fetchLocationRecord, fetchPeerId, httpUrlToMultiaddr, isCapabilitySubset, isEvmAddress, loadManifest, locationPayloadForRecord, makePkhSpaceId, makePublicSpaceId, manifestAbilitiesUnion, multiaddrToHttpUrl, normalizeDefaults, parseCanonicalNetworkId, parseExpiry, parsePkhDid, parseRecapCapabilities, parseSpaceUri, pkhDid, principalDid, principalDidEquals, recapCaveatsEqual, resolveCloudLocation, resolveManifest, resolveManifestKnowledgeRoot, resolveTinyCloudHosts, resourceCapabilitiesToAbilitiesMap, resourceCapabilitiesToSpaceAbilitiesMap, signLocationRecord, submitHostDelegation, validateClientSession, validateLocationRecord, validateLocationRecordPayload, validateManifest, validatePersistedSessionData, verifyDidKeyEd25519Signature, verifyLocationRecord };

package/dist/index.d.ts

@@ -5331,9 +5331,25 @@ interface LocationRecordPayload {
 interface LocationRecord extends LocationRecordPayload {
     signature: string;
 }
-type LocationSource = "explicit" | "blockchain" | "centralized" | "fallback";
+/**
+ * Where a resolved TinyCloud host came from, ordered highest to lowest
+ * priority. `local-loopback` and `local-link` are probed + identity-verified
+ * (see {@link discoverLocalTinyCloudNode}); the rest are resolved the same
+ * way they always have been (no liveness probing). New local-discovery
+ * sources (e.g. a future `tunnel` or `mdns` source) slot in next to
+ * `local-link` without touching the unprobed sources below them.
+ */
+type LocationSource = "explicit" | "local-loopback" | "local-link" | "blockchain" | "centralized" | "fallback";
 declare const DEFAULT_TINYCLOUD_LOCATION_REGISTRY_URL = "https://registry.tinycloud.xyz";
 declare const DEFAULT_TINYCLOUD_FALLBACK_HOST = "https://node.tinycloud.xyz";
+/** Default local loopback node URL probed before registry/fallback resolution. */
+declare const DEFAULT_LOCAL_NODE_URL = "http://127.0.0.1:8000";
+/** Probe timeout for the local loopback candidate. No retries. */
+declare const LOCAL_LOOPBACK_PROBE_TIMEOUT_MS = 250;
+/** Probe timeout for local.tinycloud.link candidates. No retries. */
+declare const LOCAL_LINK_PROBE_TIMEOUT_MS = 750;
+/** Hostname suffix identifying a local-link tunnel candidate. */
+declare const LOCAL_LINK_HOST_SUFFIX = ".local.tinycloud.link";
 interface LocationCandidate {
     source: LocationSource;
     multiaddrs: string[];
@@ -5370,6 +5386,69 @@ interface ResolvedTinyCloudHosts {
     hosts: string[];
     location: ResolvedCloudLocation;
 }
+/**
+ * Trust-on-first-use pin store for locally-discovered node identities, keyed
+ * by candidate URL. The first successful `/info` check for a URL with no
+ * existing pin adopts and pins that node's DID; every later check for the
+ * same URL must match the pin. Implementations: CLI (profile store), web
+ * (localStorage), node-sdk (config-provided callback, else in-memory).
+ */
+interface LocalNodeIdentityStore {
+    get(url: string): string | undefined | Promise<string | undefined>;
+    set(url: string, nodeDid: string): void | Promise<void>;
+}
+/** In-memory {@link LocalNodeIdentityStore}. Does not persist across process restarts. */
+declare function createInMemoryLocalNodeIdentityStore(): LocalNodeIdentityStore;
+/**
+ * Minimal subset of the DOM `Storage` interface. Declared locally so
+ * sdk-core (no DOM lib) doesn't need to depend on browser types.
+ */
+interface WebStorageLike {
+    getItem(key: string): string | null;
+    setItem(key: string, value: string): void;
+    removeItem(key: string): void;
+}
+/** Default namespaced key {@link createLocalStorageLocalNodeIdentityStore} stores its pins under. */
+declare const DEFAULT_LOCAL_NODE_PIN_STORAGE_KEY = "tinycloud.localNodePins.v1";
+/**
+ * `localStorage`-backed {@link LocalNodeIdentityStore}, namespaced under a
+ * single JSON blob (default key {@link DEFAULT_LOCAL_NODE_PIN_STORAGE_KEY}).
+ * Falls back to an in-memory store when `localStorage` is unavailable (SSR,
+ * Node.js, sandboxed contexts that throw on access, etc.), so callers never
+ * have to branch on environment. Corrupt stored JSON is reset rather than
+ * thrown.
+ */
+declare function createLocalStorageLocalNodeIdentityStore(storage?: WebStorageLike, storageKey?: string): LocalNodeIdentityStore;
+interface DiscoverLocalTinyCloudNodeOptions {
+    /**
+     * Subject DID used to look up the registry LocationRecord for
+     * `*.local.tinycloud.link` multiaddrs (source `local-link`). Omit to skip
+     * that lookup — the local-loopback and `localLinkName` candidates don't
+     * need it.
+     */
+    subject?: string;
+    /** Enable local-node auto-discovery. Default true. */
+    autoDiscoverLocalNode?: boolean;
+    /** Local loopback node URL to probe. Default http://127.0.0.1:8000. */
+    localNodeUrl?: string;
+    /** Known `*.local.tinycloud.link` subdomain name, probed directly. */
+    localLinkName?: string;
+    /** Centralized location registry URL, used for the `local-link` registry lookup. Default https://registry.tinycloud.xyz. */
+    registryUrl?: string | null;
+    /** Expected local node DID. Wins over any pinned value; a mismatch rejects the candidate. */
+    expectedNodeDid?: string;
+    /** Pin store for trust-on-first-use identity verification. Defaults to an in-memory store. */
+    identityStore?: LocalNodeIdentityStore;
+    /** Verify the registry LocationRecord signature before trusting its `local-link` multiaddrs. Default true. */
+    verifyRecords?: boolean;
+    /** Custom fetch implementation. Defaults to globalThis.fetch. */
+    fetch?: typeof fetch;
+}
+interface DiscoveredLocalTinyCloudNode {
+    source: Extract<LocationSource, "local-loopback" | "local-link">;
+    url: string;
+    nodeDid: string;
+}
 interface ResolveTinyCloudHostsOptions {
     /** Highest-priority TinyCloud HTTP host URLs or multiaddrs supplied directly. */
     explicitHosts?: string[];
@@ -5383,6 +5462,20 @@ interface ResolveTinyCloudHostsOptions {
     fetch?: typeof fetch;
     /** Verify centralized/blockchain record signatures. Default true. */
     verifyRecords?: boolean;
+    /**
+     * Probe for a locally-running TinyCloud node before falling back to
+     * registry/hosted resolution. Default true. Setting false restores the
+     * exact pre-TC-106 resolution order (registry → fallback).
+     */
+    autoDiscoverLocalNode?: boolean;
+    /** Local loopback node URL to probe. Default http://127.0.0.1:8000. */
+    localNodeUrl?: string;
+    /** Known `*.local.tinycloud.link` subdomain name, probed directly. */
+    localLinkName?: string;
+    /** Expected local node DID. Wins over any pinned value; a mismatch rejects the candidate. */
+    expectedNodeDid?: string;
+    /** Pin store for trust-on-first-use local node identity verification. Defaults to an in-memory store. */
+    localNodeIdentityStore?: LocalNodeIdentityStore;
 }
 type LocationCandidateInput = string[] | LocationRecord | {
     multiaddrs: string[];
@@ -5411,6 +5504,23 @@ 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>;
+/**
+ * Probe for a locally-running TinyCloud node and verify its identity before
+ * trusting it. Tries, in order: the local loopback URL, the explicit
+ * `localLinkName` candidate (if given), then any `*.local.tinycloud.link`
+ * multiaddr found in the subject's registry LocationRecord (if `subject` and
+ * a registry are given). Each candidate is probed with `GET {url}/healthz`
+ * (short timeout, no retries) — any failure (refused, timeout, NXDOMAIN,
+ * offline) silently skips to the next candidate, no error, no log above
+ * debug level. A candidate that answers healthy is then identity-checked via
+ * `GET {url}/info`: if an expected DID is known (explicit or previously
+ * pinned), the node's `nodeId` DID must match or the candidate is rejected;
+ * if no expectation exists yet, the DID is trusted and pinned (TOFU).
+ *
+ * Returns `null` (never throws) when no local node is found or verified —
+ * callers fall through to their normal remote resolution.
+ */
+declare function discoverLocalTinyCloudNode(options?: DiscoverLocalTinyCloudNodeOptions): Promise<DiscoveredLocalTinyCloudNode | null>;
 declare function multiaddrToHttpUrl(input: string): string;
 declare function httpUrlToMultiaddr(input: string): string;
 declare function verifyDidKeyEd25519Signature(did: string, payload: Uint8Array, signature: Uint8Array): boolean;
@@ -5444,4 +5554,4 @@ declare const EXPIRY: {
 declare const DEFAULT_SIGNED_READ_URL_EXPIRY_MS: number;
 type ExpiryTier = keyof typeof EXPIRY;
 
-export { ACCOUNT_REGISTRY_PATH, ACCOUNT_REGISTRY_SPACE, type AbilitiesMap, type AccountApplication, type AccountApplicationListOptions, type AccountDelegation, type AccountDelegationListOptions, type AccountDelegationPage, type AccountDelegationQueryOptions, type AccountDelegationRecord, type AccountDelegationResource, type AccountDelegationRevokeOptions, type AccountIndexEnsureResult, type AccountIndexRebuildResult, type AccountIndexStatus, type AccountIndexedReadOptions, AccountService, type AccountServiceConfig, type AccountSpace, type AccountSpaceListOptions, type AccountStatus, AutoApproveSpaceCreationHandler, type AutoRejectStrategy, type AutoSignStrategy, type Bytes, type CallbackStrategy, type CanonicalAddress, type CanonicalParsedNetworkId, type CapabilityEntry, CapabilityKeyRegistry, type CapabilityKeyRegistryErrorCode, CapabilityKeyRegistryErrorCodes, CaveatedDelegationUnsupportedError, type ClientSession, ClientSessionSchema, CloudLocationResolutionError, type ComposeManifestOptions, type ComposedManifestRequest, type CreateDelegationFunction, type CreateDelegationParams, type CreateDelegationWasmParams, type CreateDelegationWasmResult, DEFAULT_DEFAULTS, DEFAULT_EXPIRY, DEFAULT_KNOWLEDGE_ROOT, DEFAULT_MANIFEST_SPACE, DEFAULT_MANIFEST_VERSION, DEFAULT_SIGNED_READ_URL_EXPIRY_MS, DEFAULT_TINYCLOUD_FALLBACK_HOST, DEFAULT_TINYCLOUD_LOCATION_REGISTRY_URL, type DelegateReceivedShareParams, type DelegatedResource, type DelegatedShareAccess, 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 DelegationRevocationReceipt, type DelegationStatus, type DidCacheKeyOptions, type DidEqualsOptions, ENCRYPTION_MANIFEST_SPACE, ENCRYPTION_PERMISSION_SERVICE, EXPIRY, type EncodedShareData, type EnsData, EnsDataSchema, type EventEmitterStrategy, type ExpiryTier, 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, IdentityParseError, 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 ManifestKnowledge, type ManifestRegistryRecord, type ManifestSecretActions, ManifestValidationError, type NodeInfo, type OpenKeyCallbackStrategy, type OpenKeySigningRequestBody, type OpenKeySigningResponseBody, type OpenKeySigningStrategyOptions, type ParseRecapFromSiwe, type PartialSiweMessage, type PermissionEntry, PermissionNotInManifestError, type PersistedSessionData, type PersistedSessionProof, type PersistedTinyCloudSession, type PkhDidParts, ProtocolMismatchError, type ReceiveOptions, type ResolveCloudLocationOptions, type ResolveTinyCloudHostsOptions, type ResolvedCapabilities, type ResolvedCloudLocation, type ResolvedDelegate, type ResolvedTinyCloudHosts, type ResourceCapability, SECRETS_SPACE, 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, VAULT_PERMISSION_SERVICE, type ValidatedPersistedSessionProof, type ValidationError, VersionCheckError, type WasmRecapEntry, actionContains, activateSessionWithHost, addressStorageKey, applyPrefix, buildSpaceUri, canonicalLocationPayload, canonicalizeAddress, canonicalizeDid, canonicalizeDidUrl, canonicalizeNetworkId, canonicalizeRecapCaveats, checkNodeInfo, composeManifestRequest, createCapabilityKeyRegistry, createOpenKeyCallbackSigningStrategy, createSharingService, createSpaceService, defaultSignStrategy, defaultSpaceCreationHandler, didCacheKey, didEquals, expandActionShortNames, expandPermissionEntries, expandPermissionEntry, fetchLocationRecord, fetchPeerId, httpUrlToMultiaddr, isCapabilitySubset, isEvmAddress, loadManifest, locationPayloadForRecord, makePkhSpaceId, makePublicSpaceId, manifestAbilitiesUnion, multiaddrToHttpUrl, normalizeDefaults, parseCanonicalNetworkId, parseExpiry, parsePkhDid, parseRecapCapabilities, parseSpaceUri, pkhDid, principalDid, principalDidEquals, recapCaveatsEqual, resolveCloudLocation, resolveManifest, resolveManifestKnowledgeRoot, resolveTinyCloudHosts, resourceCapabilitiesToAbilitiesMap, resourceCapabilitiesToSpaceAbilitiesMap, signLocationRecord, submitHostDelegation, validateClientSession, validateLocationRecord, validateLocationRecordPayload, validateManifest, validatePersistedSessionData, verifyDidKeyEd25519Signature, verifyLocationRecord };
+export { ACCOUNT_REGISTRY_PATH, ACCOUNT_REGISTRY_SPACE, type AbilitiesMap, type AccountApplication, type AccountApplicationListOptions, type AccountDelegation, type AccountDelegationListOptions, type AccountDelegationPage, type AccountDelegationQueryOptions, type AccountDelegationRecord, type AccountDelegationResource, type AccountDelegationRevokeOptions, type AccountIndexEnsureResult, type AccountIndexRebuildResult, type AccountIndexStatus, type AccountIndexedReadOptions, AccountService, type AccountServiceConfig, type AccountSpace, type AccountSpaceListOptions, type AccountStatus, AutoApproveSpaceCreationHandler, type AutoRejectStrategy, type AutoSignStrategy, type Bytes, type CallbackStrategy, type CanonicalAddress, type CanonicalParsedNetworkId, type CapabilityEntry, CapabilityKeyRegistry, type CapabilityKeyRegistryErrorCode, CapabilityKeyRegistryErrorCodes, CaveatedDelegationUnsupportedError, type ClientSession, ClientSessionSchema, CloudLocationResolutionError, type ComposeManifestOptions, type ComposedManifestRequest, type CreateDelegationFunction, type CreateDelegationParams, type CreateDelegationWasmParams, type CreateDelegationWasmResult, DEFAULT_DEFAULTS, DEFAULT_EXPIRY, DEFAULT_KNOWLEDGE_ROOT, DEFAULT_LOCAL_NODE_PIN_STORAGE_KEY, DEFAULT_LOCAL_NODE_URL, DEFAULT_MANIFEST_SPACE, DEFAULT_MANIFEST_VERSION, DEFAULT_SIGNED_READ_URL_EXPIRY_MS, DEFAULT_TINYCLOUD_FALLBACK_HOST, DEFAULT_TINYCLOUD_LOCATION_REGISTRY_URL, type DelegateReceivedShareParams, type DelegatedResource, type DelegatedShareAccess, 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 DelegationRevocationReceipt, type DelegationStatus, type DidCacheKeyOptions, type DidEqualsOptions, type DiscoverLocalTinyCloudNodeOptions, type DiscoveredLocalTinyCloudNode, ENCRYPTION_MANIFEST_SPACE, ENCRYPTION_PERMISSION_SERVICE, EXPIRY, type EncodedShareData, type EnsData, EnsDataSchema, type EventEmitterStrategy, type ExpiryTier, 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, IdentityParseError, type IngestOptions, type JWK, type KeyInfo, type KeyProvider, type KeyType, LOCAL_LINK_HOST_SUFFIX, LOCAL_LINK_PROBE_TIMEOUT_MS, LOCAL_LOOPBACK_PROBE_TIMEOUT_MS, type LocalNodeIdentityStore, type LocationCandidate, type LocationCandidateInput, type LocationRecord, type LocationRecordPayload, type LocationRecordSigner, LocationRecordValidationError, type LocationResolutionAttempt, type LocationSource, type Manifest, type ManifestDefaults, type ManifestKnowledge, type ManifestRegistryRecord, type ManifestSecretActions, ManifestValidationError, type NodeInfo, type OpenKeyCallbackStrategy, type OpenKeySigningRequestBody, type OpenKeySigningResponseBody, type OpenKeySigningStrategyOptions, type ParseRecapFromSiwe, type PartialSiweMessage, type PermissionEntry, PermissionNotInManifestError, type PersistedSessionData, type PersistedSessionProof, type PersistedTinyCloudSession, type PkhDidParts, ProtocolMismatchError, type ReceiveOptions, type ResolveCloudLocationOptions, type ResolveTinyCloudHostsOptions, type ResolvedCapabilities, type ResolvedCloudLocation, type ResolvedDelegate, type ResolvedTinyCloudHosts, type ResourceCapability, SECRETS_SPACE, 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, VAULT_PERMISSION_SERVICE, type ValidatedPersistedSessionProof, type ValidationError, VersionCheckError, type WasmRecapEntry, type WebStorageLike, actionContains, activateSessionWithHost, addressStorageKey, applyPrefix, buildSpaceUri, canonicalLocationPayload, canonicalizeAddress, canonicalizeDid, canonicalizeDidUrl, canonicalizeNetworkId, canonicalizeRecapCaveats, checkNodeInfo, composeManifestRequest, createCapabilityKeyRegistry, createInMemoryLocalNodeIdentityStore, createLocalStorageLocalNodeIdentityStore, createOpenKeyCallbackSigningStrategy, createSharingService, createSpaceService, defaultSignStrategy, defaultSpaceCreationHandler, didCacheKey, didEquals, discoverLocalTinyCloudNode, expandActionShortNames, expandPermissionEntries, expandPermissionEntry, fetchLocationRecord, fetchPeerId, httpUrlToMultiaddr, isCapabilitySubset, isEvmAddress, loadManifest, locationPayloadForRecord, makePkhSpaceId, makePublicSpaceId, manifestAbilitiesUnion, multiaddrToHttpUrl, normalizeDefaults, parseCanonicalNetworkId, parseExpiry, parsePkhDid, parseRecapCapabilities, parseSpaceUri, pkhDid, principalDid, principalDidEquals, recapCaveatsEqual, resolveCloudLocation, resolveManifest, resolveManifestKnowledgeRoot, resolveTinyCloudHosts, resourceCapabilitiesToAbilitiesMap, resourceCapabilitiesToSpaceAbilitiesMap, signLocationRecord, submitHostDelegation, validateClientSession, validateLocationRecord, validateLocationRecordPayload, validateManifest, validatePersistedSessionData, verifyDidKeyEd25519Signature, verifyLocationRecord };

package/dist/index.js

@@ -12282,6 +12282,54 @@ import { ed25519 as ed255193 } from "@noble/curves/ed25519";
 import { verifyMessage as verifyMessage2 } from "viem";
 var DEFAULT_TINYCLOUD_LOCATION_REGISTRY_URL = "https://registry.tinycloud.xyz";
 var DEFAULT_TINYCLOUD_FALLBACK_HOST = "https://node.tinycloud.xyz";
+var DEFAULT_LOCAL_NODE_URL = "http://127.0.0.1:8000";
+var LOCAL_LOOPBACK_PROBE_TIMEOUT_MS = 250;
+var LOCAL_LINK_PROBE_TIMEOUT_MS = 750;
+var LOCAL_LINK_HOST_SUFFIX = ".local.tinycloud.link";
+function createInMemoryLocalNodeIdentityStore() {
+  const pins = /* @__PURE__ */ new Map();
+  return {
+    get: (url) => pins.get(url),
+    set: (url, nodeDid) => {
+      pins.set(url, nodeDid);
+    }
+  };
+}
+var DEFAULT_LOCAL_NODE_PIN_STORAGE_KEY = "tinycloud.localNodePins.v1";
+function defaultWebStorage() {
+  try {
+    return globalThis.localStorage;
+  } catch {
+    return void 0;
+  }
+}
+function createLocalStorageLocalNodeIdentityStore(storage, storageKey = DEFAULT_LOCAL_NODE_PIN_STORAGE_KEY) {
+  const backing = storage ?? defaultWebStorage();
+  if (!backing) {
+    return createInMemoryLocalNodeIdentityStore();
+  }
+  const readPins = () => {
+    const raw = backing.getItem(storageKey);
+    if (!raw) return {};
+    try {
+      const parsed = JSON.parse(raw);
+      if (parsed !== null && typeof parsed === "object" && !Array.isArray(parsed)) {
+        return parsed;
+      }
+    } catch {
+    }
+    backing.removeItem(storageKey);
+    return {};
+  };
+  return {
+    get: (url) => readPins()[url],
+    set: (url, nodeDid) => {
+      const pins = readPins();
+      pins[url] = nodeDid;
+      backing.setItem(storageKey, JSON.stringify(pins));
+    }
+  };
+}
 var LocationRecordValidationError = class extends Error {
   constructor(message) {
     super(`Location record validation failed: ${message}`);
@@ -12408,6 +12456,33 @@ async function resolveCloudLocation(subject, options2 = {}) {
   };
 }
 async function resolveTinyCloudHosts(subject, options2 = {}) {
+  const hasExplicitHosts = options2.explicitHosts !== void 0 && options2.explicitHosts.length > 0;
+  const fetchFn = memoizeFetch(options2.fetch ?? globalThis.fetch);
+  if (!hasExplicitHosts && (options2.autoDiscoverLocalNode ?? true)) {
+    const local = await discoverLocalTinyCloudNode({
+      subject,
+      autoDiscoverLocalNode: true,
+      localNodeUrl: options2.localNodeUrl,
+      localLinkName: options2.localLinkName,
+      registryUrl: options2.registryUrl,
+      expectedNodeDid: options2.expectedNodeDid,
+      identityStore: options2.localNodeIdentityStore,
+      verifyRecords: options2.verifyRecords,
+      fetch: fetchFn
+    });
+    if (local) {
+      const multiaddrs = [httpUrlToMultiaddr(local.url)];
+      const candidate = { source: local.source, multiaddrs };
+      const location2 = {
+        subject,
+        source: local.source,
+        multiaddrs,
+        attempts: [{ source: local.source, candidate }],
+        resolvedAt: (/* @__PURE__ */ new Date()).toISOString()
+      };
+      return { hosts: [local.url], location: location2 };
+    }
+  }
   const location = await resolveCloudLocation(subject, {
     explicitMultiaddrs: hostsToMultiaddrs(options2.explicitHosts),
     blockchain: options2.blockchain,
@@ -12415,7 +12490,7 @@ async function resolveTinyCloudHosts(subject, options2 = {}) {
     fallbackMultiaddrs: hostsToMultiaddrs(
       options2.fallbackHosts === null ? void 0 : options2.fallbackHosts ?? [DEFAULT_TINYCLOUD_FALLBACK_HOST]
     ),
-    fetch: options2.fetch,
+    fetch: fetchFn,
     verifyRecords: options2.verifyRecords
   });
   return {
@@ -12423,6 +12498,181 @@ async function resolveTinyCloudHosts(subject, options2 = {}) {
     location
   };
 }
+function memoizeFetch(fetchFn) {
+  const cache2 = /* @__PURE__ */ new Map();
+  return (async (input, init) => {
+    const key = String(input);
+    let cached = cache2.get(key);
+    if (!cached) {
+      cached = fetchFn(input, init);
+      cache2.set(key, cached);
+    }
+    const response = await cached;
+    return response.clone();
+  });
+}
+async function discoverLocalTinyCloudNode(options2 = {}) {
+  if ((options2.autoDiscoverLocalNode ?? true) === false) {
+    return null;
+  }
+  const fetchFn = options2.fetch ?? globalThis.fetch;
+  const identityStore = options2.identityStore ?? defaultLocalNodeIdentityStore;
+  const staticCandidates = [
+    {
+      source: "local-loopback",
+      url: options2.localNodeUrl ?? DEFAULT_LOCAL_NODE_URL,
+      timeoutMs: LOCAL_LOOPBACK_PROBE_TIMEOUT_MS
+    }
+  ];
+  if (options2.localLinkName) {
+    if (isValidDnsLabel(options2.localLinkName)) {
+      staticCandidates.push({
+        source: "local-link",
+        url: `https://${options2.localLinkName}${LOCAL_LINK_HOST_SUFFIX}`,
+        timeoutMs: LOCAL_LINK_PROBE_TIMEOUT_MS
+      });
+    } else {
+      debugLog(
+        `localLinkName "${options2.localLinkName}" is not a valid DNS label; skipping`
+      );
+    }
+  }
+  for (const candidate of staticCandidates) {
+    const adopted = await probeAndVerifyLocalCandidate(
+      candidate,
+      fetchFn,
+      identityStore,
+      options2.expectedNodeDid
+    );
+    if (adopted) {
+      return adopted;
+    }
+  }
+  const registryCandidates = await fetchRegistryLocalLinkCandidates(
+    options2,
+    fetchFn,
+    staticCandidates
+  );
+  for (const candidate of registryCandidates) {
+    const adopted = await probeAndVerifyLocalCandidate(
+      candidate,
+      fetchFn,
+      identityStore,
+      options2.expectedNodeDid
+    );
+    if (adopted) {
+      return adopted;
+    }
+  }
+  return null;
+}
+var defaultLocalNodeIdentityStore = createInMemoryLocalNodeIdentityStore();
+function debugLog(message) {
+  console.debug(`[tinycloud:location] ${message}`);
+}
+async function probeAndVerifyLocalCandidate(candidate, fetchFn, identityStore, expectedNodeDid) {
+  const healthy = await probeHealthz(candidate.url, candidate.timeoutMs, fetchFn);
+  if (!healthy) {
+    return null;
+  }
+  const info = await fetchLocalNodeInfo(candidate.url, candidate.timeoutMs, fetchFn);
+  if (!info?.nodeDid) {
+    debugLog(`local node at ${candidate.url} did not report a nodeId DID; skipping`);
+    return null;
+  }
+  const pinnedNodeDid = await identityStore.get(candidate.url);
+  const expected = expectedNodeDid ?? pinnedNodeDid;
+  if (expected !== void 0 && expected !== info.nodeDid) {
+    debugLog(
+      `local node DID mismatch at ${candidate.url}: expected ${expected}, got ${info.nodeDid}`
+    );
+    return null;
+  }
+  if (pinnedNodeDid === void 0 || expectedNodeDid !== void 0) {
+    await identityStore.set(candidate.url, info.nodeDid);
+  }
+  return { source: candidate.source, url: candidate.url, nodeDid: info.nodeDid };
+}
+async function fetchRegistryLocalLinkCandidates(options2, fetchFn, existingCandidates) {
+  if (!options2.subject || options2.registryUrl === null) {
+    return [];
+  }
+  const registryUrl = options2.registryUrl ?? DEFAULT_TINYCLOUD_LOCATION_REGISTRY_URL;
+  try {
+    const record = await fetchLocationRecord(registryUrl, options2.subject, fetchFn);
+    if (!record) {
+      return [];
+    }
+    const shouldVerify = options2.verifyRecords ?? true;
+    if (shouldVerify && !await verifyLocationRecord(record)) {
+      debugLog(
+        `registry record signature invalid for ${options2.subject}; skipping local-link lookup`
+      );
+      return [];
+    }
+    return extractLocalLinkUrls(record).filter((url) => !existingCandidates.some((c) => c.url === url)).map((url) => ({
+      source: "local-link",
+      url,
+      timeoutMs: LOCAL_LINK_PROBE_TIMEOUT_MS
+    }));
+  } catch {
+    return [];
+  }
+}
+function extractLocalLinkUrls(record) {
+  if (!record) {
+    return [];
+  }
+  const urls = [];
+  for (const addr of record.multiaddrs) {
+    let url;
+    try {
+      url = multiaddrToHttpUrl(addr);
+    } catch {
+      continue;
+    }
+    if (isLocalLinkUrl(url)) {
+      urls.push(url);
+    }
+  }
+  return urls;
+}
+var DNS_LABEL_REGEX = /^[a-z0-9]([a-z0-9-]{1,30}[a-z0-9])?$/;
+function isValidDnsLabel(value) {
+  return DNS_LABEL_REGEX.test(value);
+}
+function isLocalLinkUrl(url) {
+  try {
+    const parsed = new URL(url);
+    return parsed.protocol === "https:" && parsed.hostname.endsWith(LOCAL_LINK_HOST_SUFFIX);
+  } catch {
+    return false;
+  }
+}
+async function probeHealthz(url, timeoutMs, fetchFn) {
+  try {
+    const response = await fetchFn(`${url.replace(/\/$/, "")}/healthz`, {
+      signal: AbortSignal.timeout(timeoutMs)
+    });
+    return response.ok;
+  } catch {
+    return false;
+  }
+}
+async function fetchLocalNodeInfo(url, timeoutMs, fetchFn) {
+  try {
+    const response = await fetchFn(`${url.replace(/\/$/, "")}/info`, {
+      signal: AbortSignal.timeout(timeoutMs)
+    });
+    if (!response.ok) {
+      return null;
+    }
+    const body = await response.json();
+    return { nodeDid: body.nodeId };
+  } catch {
+    return null;
+  }
+}
 function multiaddrToHttpUrl(input) {
   const uri = multiaddrToUri(multiaddr(input));
   if (!uri.startsWith("http://") && !uri.startsWith("https://")) {
@@ -12698,6 +12948,8 @@ export {
   DEFAULT_EXPIRY,
   DEFAULT_KEY_VERSION,
   DEFAULT_KNOWLEDGE_ROOT,
+  DEFAULT_LOCAL_NODE_PIN_STORAGE_KEY,
+  DEFAULT_LOCAL_NODE_URL,
   DEFAULT_MANIFEST_SPACE,
   DEFAULT_MANIFEST_VERSION,
   DEFAULT_SIGNED_READ_URL_EXPIRY_MS,
@@ -12732,6 +12984,9 @@ export {
   KV,
   KVService2 as KVService,
   LISTEN_SQL_STATEMENT_CATALOG,
+  LOCAL_LINK_HOST_SUFFIX,
+  LOCAL_LINK_PROBE_TIMEOUT_MS,
+  LOCAL_LOOPBACK_PROBE_TIMEOUT_MS,
   LocationRecordValidationError,
   ManifestValidationError,
   NETWORK_NAME_PATTERN,
@@ -12827,6 +13082,8 @@ export {
   createAndSignPolicyStatus,
   createAndSignSignedObject,
   createCapabilityKeyRegistry,
+  createInMemoryLocalNodeIdentityStore,
+  createLocalStorageLocalNodeIdentityStore,
   createOpenKeyCallbackSigningStrategy,
   createSharingService,
   createSpaceService,
@@ -12842,6 +13099,7 @@ export {
   didCacheKey,
   didEquals,
   disableTinyCloudDebug,
+  discoverLocalTinyCloudNode,
   discoverNetwork,
   enableTinyCloudDebug,
   encryptToNetwork,