@tinycloud/node-sdk 2.3.1-beta.0 → 2.4.0-beta.10

package/dist/{core-D2hPECHW.d.cts → core-DiVEwp2P.d.cts}

@@ -1,4 +1,4 @@
-import { ISessionStorage, PersistedSessionData, AutoSignStrategy, AutoRejectStrategy, CallbackStrategy, IUserAuthorization, ISigner, ISpaceCreationHandler, IWasmBindings, SiweConfig, Manifest, ComposedManifestRequest, ClientSession, TinyCloudSession, Extension, SignInOptions, Delegation, DelegatedResource, TelemetryConfig, IKVService, ISQLService, IDuckDbService, IHooksService, INotificationHandler, IENSResolver, IDataVaultService, IEncryptionService, NetworkDescriptor, ISecretsService, ICapabilityKeyRegistry, PermissionEntry, DelegationManager, ISpaceService, ISpace, ISharingService, CreateDelegationParams, DelegationResult, ResolvedDelegate, KeyProvider, ISessionManager, JWK } from '@tinycloud/sdk-core';
+import { ISessionStorage, PersistedSessionData, AutoSignStrategy, AutoRejectStrategy, CallbackStrategy, IUserAuthorization, ISigner, ISpaceCreationHandler, IWasmBindings, SiweConfig, Manifest, ComposedManifestRequest, ClientSession, TinyCloudSession, Extension, SignInOptions, Delegation, DelegatedResource, PermissionEntry, TelemetryConfig, IKVService, ISQLService, IDuckDbService, IHooksService, INotificationHandler, IENSResolver, AccountService, IDataVaultService, IEncryptionService, NetworkDescriptor, ISecretsService, ICapabilityKeyRegistry, DelegationManager, ISpaceService, ISpace, ISharingService, CreateDelegationParams, DelegationResult, ResolvedDelegate, KeyProvider, ISessionManager, JWK } from '@tinycloud/sdk-core';
 import { EventEmitter } from 'events';
 import { InvokeFunction } from '@tinycloud/sdk-services';
 
@@ -540,6 +540,69 @@ interface PortableDelegation extends Omit<Delegation, "isRevoked"> {
      */
     resources?: DelegatedResource[];
 }
+/**
+ * The transport shape `tc auth request --emit` produces and that an owner
+ * grants to its requester. Only the fields the grant logic needs are declared;
+ * the CLI artifact carries more (posture, captured command, ...) and remains a
+ * structural superset of this interface.
+ */
+interface AuthRequestArtifact {
+    kind: "tinycloud.auth.request";
+    version: 1;
+    requestId: string;
+    /** The requester's session DID — the audience the grant is issued to. */
+    sessionDid: string;
+    /** The capabilities the requester is asking the owner to delegate. */
+    requested: PermissionEntry[];
+    /** Optional lifetime override carried from the request. */
+    requestedExpiry?: string | number;
+}
+/**
+ * The transport shape returned by {@link grantAuthRequest} (and written by
+ * `tc auth grant`). `tc auth import` accepts this artifact directly.
+ */
+interface AuthDelegationArtifact {
+    kind: "tinycloud.auth.delegation";
+    version: 1;
+    requestId: string;
+    delegationCid: string;
+    delegation: PortableDelegation;
+    permissions: PermissionEntry[];
+    expiry: string;
+    /** Whether issuing the delegation triggered a wallet prompt. */
+    prompted: boolean;
+}
+/**
+ * Minimal owner-side capability {@link grantAuthRequest} needs: the signed
+ * `delegateTo` primitive. `TinyCloudNode` satisfies this directly; web/SDK
+ * contexts can supply any object that exposes the same method.
+ */
+interface DelegationAuthority {
+    delegateTo(did: string, permissions: PermissionEntry[], options?: {
+        expiry?: string | number;
+        forceWalletSign?: boolean;
+    }): Promise<{
+        delegation: PortableDelegation;
+        prompted: boolean;
+    }>;
+}
+/**
+ * Turn a delegation REQUEST into a signed GRANT.
+ *
+ * Lifts the body of `tc auth grant` into the SDK so the request→grant
+ * handshake is callable programmatically (future SDK/web owner tooling and the
+ * KV delegation inbox), with the CLI verb reduced to a thin wrapper. The owner
+ * `authority` (a `TinyCloudNode`) signs a delegation scoped to exactly the
+ * requested caps, audienced to the requester's `sessionDid`, honoring the
+ * request's expiry. The returned artifact round-trips through `tc auth import`.
+ *
+ * Authorization is enforced cryptographically by `delegateTo`: caps that are
+ * not derivable from the owner's own session capability chain are rejected
+ * (it throws), so this never widens authority the owner doesn't hold.
+ */
+declare function grantAuthRequest(authority: DelegationAuthority, request: AuthRequestArtifact, options?: {
+    expiry?: string | number;
+}): Promise<AuthDelegationArtifact>;
 /**
  * Serialize a PortableDelegation for transport (e.g., over network).
  */
@@ -796,6 +859,7 @@ declare class TinyCloudNode {
     private _encryption?;
     private _baseSecrets?;
     private _secrets?;
+    private _account?;
     /** Cached public KV with proper delegation (set by ensurePublicSpace) */
     private _publicKV?;
     /** Session key ID - always available */
@@ -898,6 +962,15 @@ declare class TinyCloudNode {
      * Available after signIn().
      */
     get spaceId(): string | undefined;
+    /**
+     * Get the account space ID for this wallet identity.
+     * Available after wallet-backed sign-in or a restored session with address metadata.
+     */
+    get accountSpaceId(): string | undefined;
+    /**
+     * Account-level application and delegation helpers.
+     */
+    get account(): AccountService;
     /**
      * Get the current TinyCloud session.
      * Available after signIn().
@@ -913,7 +986,53 @@ declare class TinyCloudNode {
     signIn(options?: SignInOptions): Promise<void>;
     private ownedSpaceId;
     private writeManifestRegistryRecords;
-    private ensureOwnedSpaceHosted;
+    private scheduleAccountRegistrySync;
+    private withAccountRegistryRetry;
+    private requestedEncryptionNetworkIds;
+    private ensureRequestedEncryptionNetworks;
+    private ensureOwnedSpaceHostedById;
+    /**
+     * Host one of this user's owned spaces by name (e.g. `"applications"`).
+     *
+     * Resolves the name to the owned space URI
+     * (`tinycloud:pkh:eip155:<chain>:<addr>:<name>`) and registers it on the
+     * server via the host-SIWE delegation flow, so subsequent KV/SQL writes to
+     * that space succeed instead of returning `404 - Space not found`. The
+     * caller is the root authority of their own owned spaces, so no additional
+     * delegation is required.
+     *
+     * Unlike {@link ensureOwnedSpaceHostedById}, this always submits the host
+     * delegation rather than inferring hosting from session activation: a space
+     * the current session has never referenced is reported neither as
+     * `activated` nor `skipped`, so activation-based detection would wrongly
+     * skip the host. The host SIWE is idempotent server-side, so re-hosting an
+     * existing space is a safe no-op. Must be called after {@link signIn}.
+     *
+     * @param name - The owned space name (e.g. `"applications"`).
+     * @returns The hosted space URI.
+     */
+    hostOwnedSpace(name: string): Promise<string>;
+    /**
+     * Ensure one of this user's owned spaces (e.g. `"secrets"`) is hosted on the
+     * server.
+     *
+     * At sign-in, a full-authority session auto-hosts the owner's `secrets`
+     * space, but a session created with a manifest / capabilityRequest does not.
+     * Such a session can therefore hold valid `tinycloud.kv/*` capabilities for
+     * the owned `secrets` space yet still fail its first scoped
+     * `secrets.put(...)` with `404 Space not found`, because the space was never
+     * registered on the node.
+     *
+     * Calling this resolves `name` to the owner's owned-space URI
+     * (`tinycloud:pkh:eip155:<chain>:<addr>:<name>`) and hosts it via the
+     * host-SIWE delegation flow. The host SIWE is idempotent server-side, so it
+     * is safe to call whether or not the space already exists; do not gate it on
+     * a prior existence check. Must be called after {@link signIn}.
+     *
+     * @param name - The owned space name (e.g. `"secrets"`).
+     * @returns The hosted owned-space URI.
+     */
+    ensureOwnedSpaceHosted(name: string): Promise<string>;
     /**
      * Restore a previously established session from stored delegation data.
      *
@@ -1108,7 +1227,7 @@ declare class TinyCloudNode {
     get encryption(): IEncryptionService;
     getEncryptionNetwork(nameOrNetworkId?: string): Promise<NetworkDescriptor | null>;
     createEncryptionNetwork(name?: string): Promise<NetworkDescriptor>;
-    ensureEncryptionNetwork(name?: string): Promise<NetworkDescriptor>;
+    ensureEncryptionNetwork(nameOrNetworkId?: string): Promise<NetworkDescriptor>;
     /**
      * App-facing secrets API backed by the `secrets` space vault.
      */
@@ -1454,6 +1573,8 @@ declare class TinyCloudNode {
     private findGrantForOperation;
     private pruneExpiredRuntimePermissionGrants;
     private operationCovers;
+    private spaceIdsEqual;
+    private normalizeSpaceAddress;
     private actionContains;
     private invocationServiceName;
     private isEncryptionNetworkOperation;
@@ -1648,4 +1769,4 @@ declare class WasmKeyProvider implements KeyProvider {
  */
 declare function createWasmKeyProvider(sessionManager: SessionManagerWithListing): WasmKeyProvider;
 
-export { type DelegateToOptions as D, FileSessionStorage as F, MemorySessionStorage as M, type NodeEventEmitterStrategy as N, type PortableDelegation as P, type RestorableSession as R, type SignStrategy as S, TinyCloudNode as T, WasmKeyProvider as W, type DelegateToResult as a, DelegatedAccess as b, NodeUserAuthorization as c, type NodeUserAuthorizationConfig as d, type RuntimePermissionGrantOptions as e, type TinyCloudNodeConfig as f, type WasmKeyProviderConfig as g, createWasmKeyProvider as h, defaultSignStrategy as i, deserializeDelegation as j, serializeDelegation as s };
+export { type AuthDelegationArtifact as A, type DelegateToOptions as D, FileSessionStorage as F, MemorySessionStorage as M, type NodeEventEmitterStrategy as N, type PortableDelegation as P, type RestorableSession as R, type SignStrategy as S, TinyCloudNode as T, WasmKeyProvider as W, type AuthRequestArtifact as a, type DelegateToResult as b, DelegatedAccess as c, type DelegationAuthority as d, NodeUserAuthorization as e, type NodeUserAuthorizationConfig as f, type RuntimePermissionGrantOptions as g, type TinyCloudNodeConfig as h, type WasmKeyProviderConfig as i, createWasmKeyProvider as j, defaultSignStrategy as k, deserializeDelegation as l, grantAuthRequest as m, serializeDelegation as s };

package/dist/{core-D2hPECHW.d.ts → core-DiVEwp2P.d.ts}

@@ -1,4 +1,4 @@
-import { ISessionStorage, PersistedSessionData, AutoSignStrategy, AutoRejectStrategy, CallbackStrategy, IUserAuthorization, ISigner, ISpaceCreationHandler, IWasmBindings, SiweConfig, Manifest, ComposedManifestRequest, ClientSession, TinyCloudSession, Extension, SignInOptions, Delegation, DelegatedResource, TelemetryConfig, IKVService, ISQLService, IDuckDbService, IHooksService, INotificationHandler, IENSResolver, IDataVaultService, IEncryptionService, NetworkDescriptor, ISecretsService, ICapabilityKeyRegistry, PermissionEntry, DelegationManager, ISpaceService, ISpace, ISharingService, CreateDelegationParams, DelegationResult, ResolvedDelegate, KeyProvider, ISessionManager, JWK } from '@tinycloud/sdk-core';
+import { ISessionStorage, PersistedSessionData, AutoSignStrategy, AutoRejectStrategy, CallbackStrategy, IUserAuthorization, ISigner, ISpaceCreationHandler, IWasmBindings, SiweConfig, Manifest, ComposedManifestRequest, ClientSession, TinyCloudSession, Extension, SignInOptions, Delegation, DelegatedResource, PermissionEntry, TelemetryConfig, IKVService, ISQLService, IDuckDbService, IHooksService, INotificationHandler, IENSResolver, AccountService, IDataVaultService, IEncryptionService, NetworkDescriptor, ISecretsService, ICapabilityKeyRegistry, DelegationManager, ISpaceService, ISpace, ISharingService, CreateDelegationParams, DelegationResult, ResolvedDelegate, KeyProvider, ISessionManager, JWK } from '@tinycloud/sdk-core';
 import { EventEmitter } from 'events';
 import { InvokeFunction } from '@tinycloud/sdk-services';
 
@@ -540,6 +540,69 @@ interface PortableDelegation extends Omit<Delegation, "isRevoked"> {
      */
     resources?: DelegatedResource[];
 }
+/**
+ * The transport shape `tc auth request --emit` produces and that an owner
+ * grants to its requester. Only the fields the grant logic needs are declared;
+ * the CLI artifact carries more (posture, captured command, ...) and remains a
+ * structural superset of this interface.
+ */
+interface AuthRequestArtifact {
+    kind: "tinycloud.auth.request";
+    version: 1;
+    requestId: string;
+    /** The requester's session DID — the audience the grant is issued to. */
+    sessionDid: string;
+    /** The capabilities the requester is asking the owner to delegate. */
+    requested: PermissionEntry[];
+    /** Optional lifetime override carried from the request. */
+    requestedExpiry?: string | number;
+}
+/**
+ * The transport shape returned by {@link grantAuthRequest} (and written by
+ * `tc auth grant`). `tc auth import` accepts this artifact directly.
+ */
+interface AuthDelegationArtifact {
+    kind: "tinycloud.auth.delegation";
+    version: 1;
+    requestId: string;
+    delegationCid: string;
+    delegation: PortableDelegation;
+    permissions: PermissionEntry[];
+    expiry: string;
+    /** Whether issuing the delegation triggered a wallet prompt. */
+    prompted: boolean;
+}
+/**
+ * Minimal owner-side capability {@link grantAuthRequest} needs: the signed
+ * `delegateTo` primitive. `TinyCloudNode` satisfies this directly; web/SDK
+ * contexts can supply any object that exposes the same method.
+ */
+interface DelegationAuthority {
+    delegateTo(did: string, permissions: PermissionEntry[], options?: {
+        expiry?: string | number;
+        forceWalletSign?: boolean;
+    }): Promise<{
+        delegation: PortableDelegation;
+        prompted: boolean;
+    }>;
+}
+/**
+ * Turn a delegation REQUEST into a signed GRANT.
+ *
+ * Lifts the body of `tc auth grant` into the SDK so the request→grant
+ * handshake is callable programmatically (future SDK/web owner tooling and the
+ * KV delegation inbox), with the CLI verb reduced to a thin wrapper. The owner
+ * `authority` (a `TinyCloudNode`) signs a delegation scoped to exactly the
+ * requested caps, audienced to the requester's `sessionDid`, honoring the
+ * request's expiry. The returned artifact round-trips through `tc auth import`.
+ *
+ * Authorization is enforced cryptographically by `delegateTo`: caps that are
+ * not derivable from the owner's own session capability chain are rejected
+ * (it throws), so this never widens authority the owner doesn't hold.
+ */
+declare function grantAuthRequest(authority: DelegationAuthority, request: AuthRequestArtifact, options?: {
+    expiry?: string | number;
+}): Promise<AuthDelegationArtifact>;
 /**
  * Serialize a PortableDelegation for transport (e.g., over network).
  */
@@ -796,6 +859,7 @@ declare class TinyCloudNode {
     private _encryption?;
     private _baseSecrets?;
     private _secrets?;
+    private _account?;
     /** Cached public KV with proper delegation (set by ensurePublicSpace) */
     private _publicKV?;
     /** Session key ID - always available */
@@ -898,6 +962,15 @@ declare class TinyCloudNode {
      * Available after signIn().
      */
     get spaceId(): string | undefined;
+    /**
+     * Get the account space ID for this wallet identity.
+     * Available after wallet-backed sign-in or a restored session with address metadata.
+     */
+    get accountSpaceId(): string | undefined;
+    /**
+     * Account-level application and delegation helpers.
+     */
+    get account(): AccountService;
     /**
      * Get the current TinyCloud session.
      * Available after signIn().
@@ -913,7 +986,53 @@ declare class TinyCloudNode {
     signIn(options?: SignInOptions): Promise<void>;
     private ownedSpaceId;
     private writeManifestRegistryRecords;
-    private ensureOwnedSpaceHosted;
+    private scheduleAccountRegistrySync;
+    private withAccountRegistryRetry;
+    private requestedEncryptionNetworkIds;
+    private ensureRequestedEncryptionNetworks;
+    private ensureOwnedSpaceHostedById;
+    /**
+     * Host one of this user's owned spaces by name (e.g. `"applications"`).
+     *
+     * Resolves the name to the owned space URI
+     * (`tinycloud:pkh:eip155:<chain>:<addr>:<name>`) and registers it on the
+     * server via the host-SIWE delegation flow, so subsequent KV/SQL writes to
+     * that space succeed instead of returning `404 - Space not found`. The
+     * caller is the root authority of their own owned spaces, so no additional
+     * delegation is required.
+     *
+     * Unlike {@link ensureOwnedSpaceHostedById}, this always submits the host
+     * delegation rather than inferring hosting from session activation: a space
+     * the current session has never referenced is reported neither as
+     * `activated` nor `skipped`, so activation-based detection would wrongly
+     * skip the host. The host SIWE is idempotent server-side, so re-hosting an
+     * existing space is a safe no-op. Must be called after {@link signIn}.
+     *
+     * @param name - The owned space name (e.g. `"applications"`).
+     * @returns The hosted space URI.
+     */
+    hostOwnedSpace(name: string): Promise<string>;
+    /**
+     * Ensure one of this user's owned spaces (e.g. `"secrets"`) is hosted on the
+     * server.
+     *
+     * At sign-in, a full-authority session auto-hosts the owner's `secrets`
+     * space, but a session created with a manifest / capabilityRequest does not.
+     * Such a session can therefore hold valid `tinycloud.kv/*` capabilities for
+     * the owned `secrets` space yet still fail its first scoped
+     * `secrets.put(...)` with `404 Space not found`, because the space was never
+     * registered on the node.
+     *
+     * Calling this resolves `name` to the owner's owned-space URI
+     * (`tinycloud:pkh:eip155:<chain>:<addr>:<name>`) and hosts it via the
+     * host-SIWE delegation flow. The host SIWE is idempotent server-side, so it
+     * is safe to call whether or not the space already exists; do not gate it on
+     * a prior existence check. Must be called after {@link signIn}.
+     *
+     * @param name - The owned space name (e.g. `"secrets"`).
+     * @returns The hosted owned-space URI.
+     */
+    ensureOwnedSpaceHosted(name: string): Promise<string>;
     /**
      * Restore a previously established session from stored delegation data.
      *
@@ -1108,7 +1227,7 @@ declare class TinyCloudNode {
     get encryption(): IEncryptionService;
     getEncryptionNetwork(nameOrNetworkId?: string): Promise<NetworkDescriptor | null>;
     createEncryptionNetwork(name?: string): Promise<NetworkDescriptor>;
-    ensureEncryptionNetwork(name?: string): Promise<NetworkDescriptor>;
+    ensureEncryptionNetwork(nameOrNetworkId?: string): Promise<NetworkDescriptor>;
     /**
      * App-facing secrets API backed by the `secrets` space vault.
      */
@@ -1454,6 +1573,8 @@ declare class TinyCloudNode {
     private findGrantForOperation;
     private pruneExpiredRuntimePermissionGrants;
     private operationCovers;
+    private spaceIdsEqual;
+    private normalizeSpaceAddress;
     private actionContains;
     private invocationServiceName;
     private isEncryptionNetworkOperation;
@@ -1648,4 +1769,4 @@ declare class WasmKeyProvider implements KeyProvider {
  */
 declare function createWasmKeyProvider(sessionManager: SessionManagerWithListing): WasmKeyProvider;
 
-export { type DelegateToOptions as D, FileSessionStorage as F, MemorySessionStorage as M, type NodeEventEmitterStrategy as N, type PortableDelegation as P, type RestorableSession as R, type SignStrategy as S, TinyCloudNode as T, WasmKeyProvider as W, type DelegateToResult as a, DelegatedAccess as b, NodeUserAuthorization as c, type NodeUserAuthorizationConfig as d, type RuntimePermissionGrantOptions as e, type TinyCloudNodeConfig as f, type WasmKeyProviderConfig as g, createWasmKeyProvider as h, defaultSignStrategy as i, deserializeDelegation as j, serializeDelegation as s };
+export { type AuthDelegationArtifact as A, type DelegateToOptions as D, FileSessionStorage as F, MemorySessionStorage as M, type NodeEventEmitterStrategy as N, type PortableDelegation as P, type RestorableSession as R, type SignStrategy as S, TinyCloudNode as T, WasmKeyProvider as W, type AuthRequestArtifact as a, type DelegateToResult as b, DelegatedAccess as c, type DelegationAuthority as d, NodeUserAuthorization as e, type NodeUserAuthorizationConfig as f, type RuntimePermissionGrantOptions as g, type TinyCloudNodeConfig as h, type WasmKeyProviderConfig as i, createWasmKeyProvider as j, defaultSignStrategy as k, deserializeDelegation as l, grantAuthRequest as m, serializeDelegation as s };