@tinycloud/node-sdk 3.12.0-beta.2 → 3.12.0-beta.3

package/README.md

@@ -1,5 +1,44 @@
 # @tinycloud/node-sdk
 
+## Registry v2 resource routing
+
+Node SDK and the Web SDK's shared Node client use owner-signed registry v2 records by default. Set `tinycloudRegistryUrl` to select a registry; isolated development may use a loopback HTTP origin.
+
+Routing uses the complete space URI, not a short space name or a single account-wide host. Reads use that space's listed members; writes target every listed `read-write` member. Read-only members may register a session and host their listed replica, but do not receive ordinary writes. Advertised node DIDs are checked against `/info` and `/.well-known/tinycloud/node-keys` before use.
+
+Encryption is resolved separately: descriptor reads, network creation, and decrypt requests use the signed `encryptionNode`, including its invocation audience. A data-space host does not become an encryption destination, or vice versa.
+
+Explicit `host`, saved-profile hosts, local discovery, and new-user defaults are onboarding hints. The lookup checks v2 first, then v1 to distinguish absence from an existing v1 registration. Cold HTTP5xx, transport errors and timeouts without cached or remembered registration retain configured/default-host compatibility, including direct Core callers without a cache adapter; the verdict is marked `offline`, not genuine registry absence. HTTP4xx refusals, v1-only registrations, corrupt caches, invalid responses, remembered registrations, empty registered memberships and missing encryption destinations never authorize fallback. Signed strings are validated without rewriting them.
+
+`NodeNotRespondingError` has code `NODE_NOT_RESPONDING`. Registry refusals and node-identity mismatches remain distinct errors. Multi-node writes are not atomic: `PartialNodeWriteError` exposes `succeeded` URLs and `failed` destinations/statuses/causes so callers do not mistake incomplete writes for success.
+
+Mixed signed grants register unchanged on the union of their listed data destinations and `encryptionNode`. Restoring a stored valid grant does not request new consent when a destination is unavailable: canonical operations preserve `NODE_NOT_RESPONDING`, `NODE_IDENTITY_MISMATCH`, and `REGISTRY_UNAVAILABLE` separately from invalid or expired authority.
+
+Request-bound imports keep the original request/profile binding. A differing grant transport host is accepted only after validated permissions resolve through verified full-resource registry memberships; the derived destination replaces neither the saved hint nor signed bytes. Genuine no-entry still requires the original host match.
+
+### Signed registry cache
+
+`registryCacheStore` accepts a `RegistryCacheStore` from `@tinycloud/sdk-core`; the default is in-memory. The store keeps the exact fetched UTF-8 response text separately from `ownerKey`, `sequence` and `fetchedAt` metadata. EOA keys use the canonical EIP-55 address across wallet chains; `did:key` keys remain exact. Every read and replacement comparison reuses the canonical signed-v2 verifier.
+
+Persistent adapters implement `get`, required `getRevision(ownerKey)`, atomic `update(ownerKey, (current, revision) => ...)`, and `delete(ownerKey, expectedRevision?, maximumSequence?)`. The callback receives the current revision under the same store lock as the entry. Conditional deletion refuses without mutation when the revision differs or a current signed entry has a higher sequence than `maximumSequence`; validate supplied bounds as non-negative safe integers. Instrumented adapters must forward both callback arguments and all deletion arguments.
+
+Each real deletion atomically replaces the entry with `{ ownerKey, revision: previousRevision + 1, invalidated: true }`, even when already empty. Tombstones contain no signed bytes and `get` returns `undefined` for them; `getRevision` still reads their generation. Live entries may carry local `revision` metadata; legacy entries without it have revision zero. Accepted updates preserve the store's revision, not a callback-supplied value. Persist the tombstone and counter in one value/file under the existing queue or per-entry lock; never use a separate counter write. Corrupt or overflowing revisions refuse.
+
+Routing captures the revision before network I/O and checks it under the commit lock and before cached fallback. A persisted positive revision remains known-owner evidence even without a sequence adapter; it is not a signed sequence. Only a higher verified sequence replaces signed bytes. Equal-sequence renewal requires the identical canonical signed payload; differing response formatting preserves exact old raw bytes. Failed, invalid, conflicting or lower-sequence responses never renew age. Keep `registrySequenceStore` for complete signed high-water history. Ordinary accepted-sequence persistence remains best-effort; authoritative deletion retains known-owner evidence before invalidating.
+
+Every owner routing decision awaits a bounded registry refresh. Overlapping refreshes coalesce per owner; later decisions fetch again, without a retry loop or polling daemon. During transport errors, timeouts or HTTP 502/503/504 only, routing may use a canonically reverified cache whose `fetchedAt` age is strictly less than one hour. HTTP 500 and every other status do not authorize warm fallback. Authoritative HTTP4xx responses and fresh signed records without the required route delete cached settings while retaining known-owner evidence; later outages do not select a default for that owner.
+
+Each caller retains registration evidence observed before joining an in-flight refresh and checks current cache/high-water state before routing. Non-replicating `restoreSession()` verifies and hydrates signed session authority locally without registry or node I/O. Later live operations still resolve fresh routing through the service graph. The first live routing decision also starts background prefetch for the canonically verified wallet owner, independently of the requested resource's owner. Web startup's hosting probe and real held-grant activation use that same boundary; local-only inspection does not. Explicitly enabled replication retains its routing and node preflight.
+
+Restored host hints install alongside the replacement session and service graph. Subsequent public delegation preparation uses that installed hint when fresh routing permits onboarding; verified signed destinations still take precedence.
+
+Actual cold fallback logs `registry unavailable; using the default node`; warm fallback logs `Storage settings are unreachable; using cached settings checked less than 1 hour ago.` Each diagnostic is emitted once per owner/client cache and fallback kind, only after a route is selected. `onRegistryFallback(reason, code?)` collects these value-free diagnostics instead of the default console warning; semantic codes are `using_default_node` and `using_cached_settings`. Background refresh alone does not warn.
+
+This is a client cache: a node that performs online registry admission still needs its own registry connectivity. It is not a whole-service-outage guarantee.
+
+Details: TC-2481
+
+
 ## Signed SIWE metadata
 
 Set `siweConfig.resources` to `urn:tinycloud:recipients:<base64url>` URI strings to include a recipients declaration in the signed SIWE. The payload uses only unpadded base64url characters (`A–Z`, `a–z`, `0–9`, `_`, `-`). Node-sdk inserts these URIs immediately before the original ReCap resource, which remains last. Ordinary sign-in, external/OpenKey preparation, and bootstrap sessions use the same insertion path; completion and session storage retain the signed message unchanged.

package/dist/{NodeUserAuthorization-B05Wjjpb.d.cts → NodeUserAuthorization-B_TFUlua.d.cts}

@@ -1,4 +1,5 @@
-import { AutoSignStrategy, AutoRejectStrategy, CallbackStrategy, CapabilityPresentationEnvelopeV1, IUserAuthorization, ISigner, ISessionStorage, ISpaceCreationHandler, RegistryPolicy, RegistrySequenceStore, OnNodeNotFound, LocalNodeIdentityStore, IWasmBindings, ISessionManager, SiweConfig, Manifest, ComposedManifestRequest, ReplicationOptions, TinyCloudSession, PersistedSessionData, ClientSession, PermissionEntry, Extension, SignRequest, SpaceHostResult, SignInOptions } from '@tinycloud/sdk-core';
+import { AutoSignStrategy, AutoRejectStrategy, CallbackStrategy, CapabilityPresentationEnvelopeV1, IUserAuthorization, ISigner, ISessionStorage, ISpaceCreationHandler, RegistryPolicy, RegistrySequenceStore, RegistryCacheStore, RegistryFallbackReason, OnNodeNotFound, LocalNodeIdentityStore, IWasmBindings, ISessionManager, SiweConfig, Manifest, ComposedManifestRequest, ReplicationOptions, TinyCloudSession, PersistedSessionData, ClientSession, PermissionEntry, Extension, SignRequest, SpaceHostResult, SignInOptions } from '@tinycloud/sdk-core';
+import { ResourceAccess, ResourceDestination } from '@tinycloud/sdk-services';
 import { EventEmitter } from 'events';
 
 /**
@@ -213,29 +214,13 @@ interface NodeUserAuthorizationConfig {
     autoCreateSpace?: boolean;
     /** Custom space creation handler. If provided, takes precedence over autoCreateSpace. */
     spaceCreationHandler?: ISpaceCreationHandler;
-    /** Explicit TinyCloud server endpoints. When omitted, signIn resolves the user's host. */
+    /** Host hints used only for owners absent from both registry namespaces. */
     tinycloudHosts?: string[];
     /** TinyCloud location registry URL. Default: https://registry.tinycloud.xyz. */
     tinycloudRegistryUrl?: string | null;
-    /**
-     * Fallback TinyCloud hosts. Default: hosted TinyCloud node. Used only by the
-     * default `registryPolicy` ("legacy-fallback"), whose silent fallback is
-     * deprecated and will be removed in a future major release.
-     */
+    /** Host hints for genuine no-entry onboarding. Never used for registered or unavailable owners. */
     tinycloudFallbackHosts?: string[] | null;
-    /**
-     * How sign-in uses the location registry when no host is configured.
-     *
-     * - `"legacy-fallback"` (default, deprecated): a registry miss or failure
-     *   silently uses `tinycloudFallbackHosts`, with a one-time warning.
-     * - `"fail-closed"`: sign-in acts on the registry verdict for the signer
-     *   address. Registered owners go to their listed hosts, unregistered owners
-     *   to `newUserHost`, and an unavailable registry is
-     *   `RegistryUnavailableError`, never a new account. Automatic space
-     *   creation is refused on a host the owner's record does not list
-     *   (`NodeRegistryEntryExistsError`) or when the registry gives no verdict
-     *   (`RegistryUnavailableError`).
-     */
+    /** Registry routing is always v2-first and fail-closed. */
     registryPolicy?: RegistryPolicy;
     /**
      * `fail-closed` only: host for owners with no registry record (and only
@@ -250,6 +235,9 @@ interface NodeUserAuthorizationConfig {
     registryChainId?: number;
     /** `fail-closed` only: highest registry sequence seen per owner. Default: in-memory. */
     registrySequenceStore?: RegistrySequenceStore;
+    registryCacheStore?: RegistryCacheStore;
+    /** Value-free warning after an actual cached-settings or default-node fallback. */
+    onRegistryFallback?: (reason: string, code?: RegistryFallbackReason) => void;
     /**
      * `fail-closed` only: called when sign-in resolves no host
      * (`NodeNotFoundError` or `RegistryUnavailableError`) to retry, use another
@@ -371,11 +359,12 @@ declare class NodeUserAuthorization implements IUserAuthorization {
     private tinycloudHosts?;
     private readonly tinycloudRegistryUrl?;
     private readonly tinycloudFallbackHosts?;
-    private readonly registryPolicy?;
     private readonly newUserHost?;
     private readonly registryChainId?;
     private readonly registrySequenceStore;
+    private readonly registryCacheStore;
     private readonly onNodeNotFound?;
+    private readonly onRegistryFallback?;
     /** Verdict from the last `fail-closed` host resolution, reused by {@link assertMayCreateSpace}. */
     private registryVerdict?;
     private readonly autoDiscoverLocalNode?;
@@ -466,13 +455,8 @@ declare class NodeUserAuthorization implements IUserAuthorization {
      * undefined for missing SIWEs and the SDK then treats the session as
      * expired-at-epoch-zero.
      *
-     * @param hosts - The TinyCloud hosts this session was created against,
-     *   as persisted in {@link PersistedSessionData.tinycloudHosts}. When
-     *   present (and non-empty) they are adopted directly so the restored
-     *   session resolves to the same node as the original sign-in without
-     *   re-running registry/fallback resolution. When absent (old session)
-     *   hosts are resolved lazily on the first host-needing call via
-     *   {@link ensureTinyCloudHosts}.
+     * @param hosts - Persisted host hints for genuine no-entry onboarding.
+     *   Current signed registry membership always takes precedence.
      */
     setRestoredTinyCloudSession(session: TinyCloudSession, hosts?: string[]): void;
     /**
@@ -486,32 +470,14 @@ declare class NodeUserAuthorization implements IUserAuthorization {
     private enqueuePersistence;
     /** @internal Atomically adopt the state staged by TinyCloudNode.restoreSession. */
     installRestoredSession(sessionManager: ISessionManager, session: TinyCloudSession | undefined, hosts?: string[], nodeFeatures?: string[]): void;
-    /**
-     * Ensure `tinycloudHosts` are resolved before a host-needing call.
-     *
-     * Fresh sign-in resolves hosts up front; a restored session may not have
-     * (old persisted sessions predate {@link PersistedSessionData.tinycloudHosts}).
-     * This guard makes a restored session resolve the node exactly like a fresh
-     * sign-in — persisted hosts are preferred (already set by
-     * {@link setRestoredTinyCloudSession}), otherwise the registry/fallback
-     * resolution runs lazily here. Idempotent: {@link resolveTinyCloudHostsForSignIn}
-     * early-returns when hosts are already set.
-     *
-     * Throws if hosts are unset and the restored session has no address/chainId
-     * to resolve from — a real failure that must surface, not be masked.
-     */
+    /** Refresh the primary space's registry destinations, including after restore. */
     ensureTinyCloudHosts(): Promise<void>;
     private resolveTinyCloudHostsForSignIn;
-    /**
-     * Space-creation guard (TC-1443). Under `registryPolicy: "fail-closed"`,
-     * throws unless the owner's registry verdict allows a space on the primary
-     * host: `NodeRegistryEntryExistsError` when the owner's record does not
-     * list it, `RegistryUnavailableError` when the registry gives no
-     * verdict. Reuses this session's sign-in verdict unless it was
-     * `unavailable`, else looks it up now (explicit-host apps). Under the
-     * default policy it returns at once and performs no lookup.
-     */
-    assertMayCreateSpace(): Promise<void>;
+    /** Current full-resource registry routing; saved hosts are only no-entry hints. */
+    resolveResourceDestinations(resource: string, access: ResourceAccess, noEntryHosts?: readonly string[]): Promise<ResourceDestination[]>;
+    get registryRecordPresent(): boolean;
+    /** Refresh membership before hosting; a saved no-entry verdict never authorizes a later creation. */
+    assertMayCreateSpace(spaceId?: string | undefined, host?: string): Promise<void>;
     private requireTinyCloudHosts;
     private get primaryTinyCloudHost();
     get nodeFeatures(): string[];

package/dist/{NodeUserAuthorization-B05Wjjpb.d.ts → NodeUserAuthorization-B_TFUlua.d.ts}

@@ -1,4 +1,5 @@
-import { AutoSignStrategy, AutoRejectStrategy, CallbackStrategy, CapabilityPresentationEnvelopeV1, IUserAuthorization, ISigner, ISessionStorage, ISpaceCreationHandler, RegistryPolicy, RegistrySequenceStore, OnNodeNotFound, LocalNodeIdentityStore, IWasmBindings, ISessionManager, SiweConfig, Manifest, ComposedManifestRequest, ReplicationOptions, TinyCloudSession, PersistedSessionData, ClientSession, PermissionEntry, Extension, SignRequest, SpaceHostResult, SignInOptions } from '@tinycloud/sdk-core';
+import { AutoSignStrategy, AutoRejectStrategy, CallbackStrategy, CapabilityPresentationEnvelopeV1, IUserAuthorization, ISigner, ISessionStorage, ISpaceCreationHandler, RegistryPolicy, RegistrySequenceStore, RegistryCacheStore, RegistryFallbackReason, OnNodeNotFound, LocalNodeIdentityStore, IWasmBindings, ISessionManager, SiweConfig, Manifest, ComposedManifestRequest, ReplicationOptions, TinyCloudSession, PersistedSessionData, ClientSession, PermissionEntry, Extension, SignRequest, SpaceHostResult, SignInOptions } from '@tinycloud/sdk-core';
+import { ResourceAccess, ResourceDestination } from '@tinycloud/sdk-services';
 import { EventEmitter } from 'events';
 
 /**
@@ -213,29 +214,13 @@ interface NodeUserAuthorizationConfig {
     autoCreateSpace?: boolean;
     /** Custom space creation handler. If provided, takes precedence over autoCreateSpace. */
     spaceCreationHandler?: ISpaceCreationHandler;
-    /** Explicit TinyCloud server endpoints. When omitted, signIn resolves the user's host. */
+    /** Host hints used only for owners absent from both registry namespaces. */
     tinycloudHosts?: string[];
     /** TinyCloud location registry URL. Default: https://registry.tinycloud.xyz. */
     tinycloudRegistryUrl?: string | null;
-    /**
-     * Fallback TinyCloud hosts. Default: hosted TinyCloud node. Used only by the
-     * default `registryPolicy` ("legacy-fallback"), whose silent fallback is
-     * deprecated and will be removed in a future major release.
-     */
+    /** Host hints for genuine no-entry onboarding. Never used for registered or unavailable owners. */
     tinycloudFallbackHosts?: string[] | null;
-    /**
-     * How sign-in uses the location registry when no host is configured.
-     *
-     * - `"legacy-fallback"` (default, deprecated): a registry miss or failure
-     *   silently uses `tinycloudFallbackHosts`, with a one-time warning.
-     * - `"fail-closed"`: sign-in acts on the registry verdict for the signer
-     *   address. Registered owners go to their listed hosts, unregistered owners
-     *   to `newUserHost`, and an unavailable registry is
-     *   `RegistryUnavailableError`, never a new account. Automatic space
-     *   creation is refused on a host the owner's record does not list
-     *   (`NodeRegistryEntryExistsError`) or when the registry gives no verdict
-     *   (`RegistryUnavailableError`).
-     */
+    /** Registry routing is always v2-first and fail-closed. */
     registryPolicy?: RegistryPolicy;
     /**
      * `fail-closed` only: host for owners with no registry record (and only
@@ -250,6 +235,9 @@ interface NodeUserAuthorizationConfig {
     registryChainId?: number;
     /** `fail-closed` only: highest registry sequence seen per owner. Default: in-memory. */
     registrySequenceStore?: RegistrySequenceStore;
+    registryCacheStore?: RegistryCacheStore;
+    /** Value-free warning after an actual cached-settings or default-node fallback. */
+    onRegistryFallback?: (reason: string, code?: RegistryFallbackReason) => void;
     /**
      * `fail-closed` only: called when sign-in resolves no host
      * (`NodeNotFoundError` or `RegistryUnavailableError`) to retry, use another
@@ -371,11 +359,12 @@ declare class NodeUserAuthorization implements IUserAuthorization {
     private tinycloudHosts?;
     private readonly tinycloudRegistryUrl?;
     private readonly tinycloudFallbackHosts?;
-    private readonly registryPolicy?;
     private readonly newUserHost?;
     private readonly registryChainId?;
     private readonly registrySequenceStore;
+    private readonly registryCacheStore;
     private readonly onNodeNotFound?;
+    private readonly onRegistryFallback?;
     /** Verdict from the last `fail-closed` host resolution, reused by {@link assertMayCreateSpace}. */
     private registryVerdict?;
     private readonly autoDiscoverLocalNode?;
@@ -466,13 +455,8 @@ declare class NodeUserAuthorization implements IUserAuthorization {
      * undefined for missing SIWEs and the SDK then treats the session as
      * expired-at-epoch-zero.
      *
-     * @param hosts - The TinyCloud hosts this session was created against,
-     *   as persisted in {@link PersistedSessionData.tinycloudHosts}. When
-     *   present (and non-empty) they are adopted directly so the restored
-     *   session resolves to the same node as the original sign-in without
-     *   re-running registry/fallback resolution. When absent (old session)
-     *   hosts are resolved lazily on the first host-needing call via
-     *   {@link ensureTinyCloudHosts}.
+     * @param hosts - Persisted host hints for genuine no-entry onboarding.
+     *   Current signed registry membership always takes precedence.
      */
     setRestoredTinyCloudSession(session: TinyCloudSession, hosts?: string[]): void;
     /**
@@ -486,32 +470,14 @@ declare class NodeUserAuthorization implements IUserAuthorization {
     private enqueuePersistence;
     /** @internal Atomically adopt the state staged by TinyCloudNode.restoreSession. */
     installRestoredSession(sessionManager: ISessionManager, session: TinyCloudSession | undefined, hosts?: string[], nodeFeatures?: string[]): void;
-    /**
-     * Ensure `tinycloudHosts` are resolved before a host-needing call.
-     *
-     * Fresh sign-in resolves hosts up front; a restored session may not have
-     * (old persisted sessions predate {@link PersistedSessionData.tinycloudHosts}).
-     * This guard makes a restored session resolve the node exactly like a fresh
-     * sign-in — persisted hosts are preferred (already set by
-     * {@link setRestoredTinyCloudSession}), otherwise the registry/fallback
-     * resolution runs lazily here. Idempotent: {@link resolveTinyCloudHostsForSignIn}
-     * early-returns when hosts are already set.
-     *
-     * Throws if hosts are unset and the restored session has no address/chainId
-     * to resolve from — a real failure that must surface, not be masked.
-     */
+    /** Refresh the primary space's registry destinations, including after restore. */
     ensureTinyCloudHosts(): Promise<void>;
     private resolveTinyCloudHostsForSignIn;
-    /**
-     * Space-creation guard (TC-1443). Under `registryPolicy: "fail-closed"`,
-     * throws unless the owner's registry verdict allows a space on the primary
-     * host: `NodeRegistryEntryExistsError` when the owner's record does not
-     * list it, `RegistryUnavailableError` when the registry gives no
-     * verdict. Reuses this session's sign-in verdict unless it was
-     * `unavailable`, else looks it up now (explicit-host apps). Under the
-     * default policy it returns at once and performs no lookup.
-     */
-    assertMayCreateSpace(): Promise<void>;
+    /** Current full-resource registry routing; saved hosts are only no-entry hints. */
+    resolveResourceDestinations(resource: string, access: ResourceAccess, noEntryHosts?: readonly string[]): Promise<ResourceDestination[]>;
+    get registryRecordPresent(): boolean;
+    /** Refresh membership before hosting; a saved no-entry verdict never authorizes a later creation. */
+    assertMayCreateSpace(spaceId?: string | undefined, host?: string): Promise<void>;
     private requireTinyCloudHosts;
     private get primaryTinyCloudHost();
     get nodeFeatures(): string[];

package/dist/{TinyCloudNode-CEFGtSWn.d.ts → TinyCloudNode-Brcu8QoX.d.cts}

@@ -1,10 +1,10 @@
 import * as _tinycloud_sdk_core from '@tinycloud/sdk-core';
-import { TinyCloudSession, TelemetryConfig, ServiceContext, IKVService, ISQLService, IDuckDbService, IHooksService, CreateOwnerDelegationParams as CreateOwnerDelegationParams$1, OwnerDelegationReceipt as OwnerDelegationReceipt$1, Delegation, IWasmBindings, ISigner, StorageFullEvent, IStorageService, RegistryPolicy, RegistrySequenceStore, OnNodeNotFound, LocalNodeIdentityStore, ISessionStorage, INotificationHandler, IENSResolver, ISpaceCreationHandler, SiweConfig, Manifest, ComposedManifestRequest, RetryPolicy, ReplicationOptions, KVReplicaStorage, PermissionEntry, AccountService, SignInOptions, InvokeAnyFunction as InvokeAnyFunction$1, UnifiedPolicyCapability, RegisterPolicyV3Input, RegisterPolicyV3Receipt, CanonicalJson, ShareDeliveryAuthorizationV3Receipt, IDataVaultService, IEncryptionService, NetworkDescriptor, ISecretsService, ICapabilityKeyRegistry, DelegationManager, ISpaceService, ISpace, ISharingService, DelegationResult, DelegationRevocationReceipt, DelegationStatus, ServiceSession, ReplicationControl, ResolvedDelegate } from '@tinycloud/sdk-core';
+import { TinyCloudSession, TelemetryConfig, ServiceContext, IKVService, ISQLService, IDuckDbService, IHooksService, CreateOwnerDelegationParams as CreateOwnerDelegationParams$1, OwnerDelegationReceipt as OwnerDelegationReceipt$1, Delegation, IWasmBindings, ISigner, StorageFullEvent, IStorageService, RegistryPolicy, RegistrySequenceStore, RegistryCacheStore, RegistryFallbackReason, OnNodeNotFound, LocalNodeIdentityStore, ISessionStorage, INotificationHandler, IENSResolver, ISpaceCreationHandler, SiweConfig, Manifest, ComposedManifestRequest, RetryPolicy, ReplicationOptions, KVReplicaStorage, PermissionEntry, AccountService, SignInOptions, InvokeAnyFunction as InvokeAnyFunction$1, UnifiedPolicyCapability, RegisterPolicyV3Input, RegisterPolicyV3Receipt, CanonicalJson, ShareDeliveryAuthorizationV3Receipt, IDataVaultService, IEncryptionService, NetworkDescriptor, ISecretsService, ICapabilityKeyRegistry, DelegationManager, ISpaceService, ISpace, ISharingService, DelegationResult, DelegationRevocationReceipt, DelegationStatus, ServiceSession, ReplicationControl, ResolvedDelegate } from '@tinycloud/sdk-core';
 import { ReplicaPurgeFailedEvent, ReplicaSessionStamp } from '@tinycloud/sdk-services/kv/replication';
 import { InvokeFunction, InvokeAnyFunction, FetchFunction, RequestSink, RequestLogReader } from '@tinycloud/sdk-services';
 import { NamedKeyClient } from '@tinycloud/sdk-services/encryption/named-keys';
-import { S as SpaceHosting, c as SignStrategy, a as NodeUserAuthorization, P as PreparedOpenKeyAuthorization } from './NodeUserAuthorization-B05Wjjpb.js';
-import { P as PortableDelegation, S as SessionGrantProof, e as VerifiedSessionGrant } from './delegation-BQbAuKad.js';
+import { S as SpaceHosting, c as SignStrategy, a as NodeUserAuthorization, P as PreparedOpenKeyAuthorization } from './NodeUserAuthorization-B_TFUlua.cjs';
+import { P as PortableDelegation, S as SessionGrantProof, e as VerifiedSessionGrant } from './delegation-CeOWDnBB.cjs';
 
 /**
  * The handles needed to rehydrate this delegation activation in a fresh
@@ -192,32 +192,15 @@ interface TinyCloudNodeConfig {
     signer?: ISigner;
     /** Strategy for root signature requests. Defaults to auto-sign for local keys. */
     signStrategy?: SignStrategy;
-    /** Explicit TinyCloud server URL. When omitted, signIn resolves the user's host. */
+    /** Host hint for genuine no-entry onboarding; a signed registry entry takes precedence. */
     host?: string;
     /** Build a developer request log (sanitized, in-memory, bounded). Off by default. */
     requestLog?: boolean;
     /** TinyCloud location registry URL. Default: https://registry.tinycloud.xyz. */
     tinycloudRegistryUrl?: string | null;
-    /**
-     * Fallback TinyCloud hosts. Default: hosted TinyCloud node. Used only by the
-     * default `registryPolicy` ("legacy-fallback"), whose silent fallback is
-     * deprecated and will be removed in a future major release.
-     */
+    /** Host hints for genuine no-entry onboarding. Never used for registered or unavailable owners. */
     tinycloudFallbackHosts?: string[] | null;
-    /**
-     * How sign-in uses the location registry when no `host` is configured.
-     * Default `"legacy-fallback"` (deprecated): a registry miss or failure
-     * silently uses `tinycloudFallbackHosts`, with a one-time warning.
-     * `"fail-closed"`: routing acts on the registry verdict for the signer
-     * address, an unavailable registry is `RegistryUnavailableError` (never a
-     * new account), record hosts are used only if HTTPS or loopback, and
-     * automatic space creation (sign-in, account bootstrap, owned-space
-     * hosting, the public space the vault creates) is refused on a host the
-     * owner's registry record does not list (`NodeRegistryEntryExistsError`)
-     * or when the registry gives no verdict. An explicit `hostOwnedSpace()`
-     * call is not guarded. `newUserHost` governs routing only: a pinned host
-     * may still create spaces for an unregistered owner.
-     */
+    /** Registry routing is always v2-first and fail-closed. */
     registryPolicy?: RegistryPolicy;
     /** `fail-closed` only: host for owners with no registry record. Default https://node.tinycloud.xyz; `null` refuses them with `NodeNotFoundError`. */
     newUserHost?: string | null;
@@ -225,9 +208,13 @@ interface TinyCloudNodeConfig {
     registryChainId?: number;
     /** `fail-closed` only: highest registry sequence seen per owner. Default: in-memory for this client. */
     registrySequenceStore?: RegistrySequenceStore;
-    /** `fail-closed` only: retry, use another host (not identity-checked; it persists with the session), or abort when sign-in resolves no host. Without it, sign-in throws. */
+    /** Exact signed-v2 responses; pass a persistent adapter to survive restarts. */
+    registryCacheStore?: RegistryCacheStore;
+    /** Value-free warning after an actual cached-settings or default-node fallback. */
+    onRegistryFallback?: (reason: string, code?: RegistryFallbackReason) => void;
+    /** Retry or abort when registry resolution fails; `use-host` is accepted only for genuine no-entry onboarding. */
     onNodeNotFound?: OnNodeNotFound;
-    /** Probe configured/registered local nodes before registry/fallback resolution. Default: true. */
+    /** Probe configured local nodes only for genuine no-entry onboarding. Default: true. */
     autoDiscoverLocalNode?: boolean;
     /** Local loopback node URL to probe. Omit to avoid probing loopback. */
     localNodeUrl?: string;
@@ -487,6 +474,7 @@ declare class TinyCloudNode {
     static registerNodeDefaults(defaults: NodeDefaults): void;
     private config;
     private readonly explicitHost?;
+    private readonly registryRefreshOwners;
     private signer;
     private auth;
     private readonly consumedOpenKeyPendings;
@@ -758,7 +746,12 @@ declare class TinyCloudNode {
     private shouldUseBootstrapSignInRequest;
     /** Sanitized developer request events; undefined unless the node was built with `requestLog: true`. */
     get requests(): RequestLogReader | undefined;
+    private throwRegistryRefusal;
     private createServiceGraphLifetime;
+    private routingDestinations;
+    /** Transport hints cannot override verified full-resource registry routing. */
+    resolveRegisteredDelegationHost(permissions: readonly PermissionEntry[], noEntryHost: string): Promise<string | undefined>;
+    private bindRoutedAudience;
     private syncResolvedHostFromAuth;
     /**
      * Install or replace the manifest that drives the SIWE recap at
@@ -811,6 +804,9 @@ declare class TinyCloudNode {
      * rather than treating a malformed session as unrestricted authority.
      */
     getVerifiedSessionCapabilities(): PermissionEntry[];
+    /** Start one background refresh for each owner derived from verified authority. */
+    refreshRegistryForCapabilities(permissions: readonly PermissionEntry[]): void;
+    private refreshRegistryOwner;
     /** Normalize signed capabilities without collapsing nested encryption into raw authority. */
     private projectSignedRecapCapabilities;
     /**
@@ -1053,23 +1049,15 @@ declare class TinyCloudNode {
      * session's recap doesn't cover it and the registry has no record; the host
      * SIWE is idempotent server-side. Must be called after {@link signIn}.
      *
-     * Under `registryPolicy: "fail-closed"`, hosting is refused with
-     * `NodeRegistryEntryExistsError` when the owner's registry record does not
-     * list the host, or `RegistryUnavailableError` when the registry gives no
-     * verdict. {@link hostOwnedSpace} itself is an explicit action and is not
-     * guarded.
+     * Current signed per-space membership is checked before both automatic and
+     * explicit hosting. Registered replicas use the session grant; no-entry
+     * onboarding retains the host-SIWE flow.
      *
      * @param name - The owned space name (e.g. `"secrets"`).
      * @returns The hosted owned-space URI.
      */
     ensureOwnedSpaceHosted(name: string): Promise<string>;
-    /**
-     * Space-creation guard (TC-1443) for the automatic hosting paths: sign-in's
-     * owned spaces, account bootstrap, {@link ensureOwnedSpaceHosted} and
-     * {@link ensurePublicSpace}. Only `registryPolicy: "fail-closed"` consults
-     * the registry ({@link NodeUserAuthorization.assertMayCreateSpace}); the
-     * default policy performs no lookup.
-     */
+    /** Refresh full-space membership before any automatic or explicit hosting. */
     private assertMayCreateSpace;
     /** Registry-policy settings shared by every authorization this client creates. */
     private registryPolicyConfig;
@@ -1151,13 +1139,8 @@ declare class TinyCloudNode {
          */
         expiresAt?: string;
         /**
-         * The TinyCloud hosts this session was created against (from
-         * {@link PersistedSessionData.tinycloudHosts}). When present they are
-         * adopted so the restored session targets the same node as the
-         * original sign-in — without this, service calls fall back to the
-         * default host and the auth layer throws "TinyCloud hosts have not
-         * been resolved". When absent (old persisted session) hosts resolve
-         * lazily via the registry/fallback on the first host-needing call.
+         * Persisted node origins are no-entry hints only. Restore resolves the
+         * current signed entry before selecting any data destination.
          */
         tinycloudHosts?: string[];
         /**
@@ -1173,21 +1156,6 @@ declare class TinyCloudNode {
     }): Promise<void>;
     private stagePrimarySessionState;
     private stageRestoredServiceGraph;
-    /**
-     * Resolve the host a restored session should target.
-     *
-     * Mirrors fresh sign-in host resolution but for the restore path:
-     * an explicit/pinned host always wins, then the hosts the session was
-     * persisted with, then a lazy registry/fallback resolution for sessions
-     * that predate the persisted `tinycloudHosts` field. Returns `undefined`
-     * only when there's nothing to resolve from (no explicit host, no
-     * persisted hosts, and no address/chainId) — in which case the existing
-     * `config.host` (default) is left in place.
-     *
-     * Resolution failures are surfaced, not swallowed: a genuinely broken
-     * registry lookup throws rather than silently falling back to a wrong host.
-     */
-    private resolveRestoredHost;
     /**
      * Resolve the currently-active TinyCloudSession, preferring the auth
      * layer's value (wallet mode) and falling back to the node-level
@@ -1290,6 +1258,7 @@ declare class TinyCloudNode {
      */
     private fetchNodeId;
     private signRawNetworkAuthorization;
+    private encryptionDestination;
     private fetchEncryptionNetworkAt;
     private createEncryptionService;
     private getEncryptionService;
@@ -1536,6 +1505,9 @@ declare class TinyCloudNode {
      * which also refuses decrypt-only grants.
      */
     verifySessionGrant(grant: SessionGrantProof): VerifiedSessionGrant;
+    private activateResourceSession;
+    private activateRoutedDelegation;
+    private activateSignedSession;
     /**
      * Install a portable runtime permission delegation into this SDK instance so
      * matching service calls and downstream `delegateTo()` calls can use it.