@tinycloud/web-sdk 3.8.0-beta.9 → 3.8.1-beta.0

package/dist/modules/tcw.d.ts

@@ -9,7 +9,7 @@
  *
  * @packageDocumentation
  */
-import { TinyCloudNode, TinyCloudNodeConfig, type BootstrapWarning, type DelegateToOptions, type DelegateToResult, type ISessionStorage, type SignStrategy, type ValidatedRuntimeDelegation, type UnifiedOwnerRootInput, type UnifiedOwnerRootReceipt, type RegisterPolicyV3Input, type RegisterPolicyV3Receipt } from "@tinycloud/node-sdk/core";
+import { TinyCloudNode, TinyCloudNodeConfig, type OpenKeyAuthorizeTinyCloud, type BootstrapWarning, type DelegateToOptions, type DelegateToResult, type ISessionStorage, type SignStrategy, type ValidatedRuntimeDelegation, type UnifiedOwnerRootInput, type UnifiedOwnerRootReceipt, type RegisterPolicyV3Input, type RegisterPolicyV3Receipt } from "@tinycloud/node-sdk/core";
 import { type LocalCopyPurgeFailedEvent } from "./replica-wiring";
 import { IKVService, ISQLService, IDuckDbService, IDataVaultService, ISecretsService, ISpaceService, ISpace, ISharingService, ICapabilityKeyRegistry, IHooksService, IEncryptionService, DelegationManager, Delegation, DelegationRevocationReceipt, Result, DelegationError, ClientSession, Extension, type TelemetryConfig, type RetryPolicy, ISpaceCreationHandler, type Manifest, type ComposedManifestRequest, type AccountService, type ResolvedDelegate, type PermissionEntry, type NetworkDescriptor, type CreateOwnerDelegationParams, type OwnerDelegationReceipt, type LocalNodeIdentityStore, type OnNodeNotFound, type RegistryPolicy, type RegistrySequenceStore, SignInOptions, type StorageFullEvent, type IStorageService } from "@tinycloud/sdk-core";
 import { type RequestPermissionsOptions } from "./requestPermissionsCore";
@@ -25,12 +25,21 @@ declare global {
         ethereum?: any;
     }
 }
+/** Signs a message for a runtime permission grant; see `TinyCloudWeb.setRuntimePermissionSigner`. */
+export interface RuntimePermissionSigner {
+    signMessage(message: string): Promise<string>;
+}
 /**
  * Configuration for TinyCloudWeb.
  *
  * Extends ClientConfig with browser-specific options.
  */
 export interface Config extends ClientConfig {
+    /** OpenKey authorize-sign client. Requires @openkey/sdk >=0.12.2; popup is the default mode. */
+    openkey?: {
+        client: OpenKeyAuthorizeTinyCloud;
+        mode?: "iframe" | "popup" | "redirect";
+    };
     /** Notifications. `throwErrors` rethrows each error's raw message asynchronously, once per burst of identical errors (200 ms window). It applies unless `ui: false` or `ui.toasts: false`, which turn off toasts and throws together, as the old `popups: false` did; `ui.button: false` leaves throws on. Toast placement and visibility are set through `ui`. */
     notifications?: NotificationConfig;
     /** Optional prefix for KV service keys */
@@ -170,6 +179,10 @@ export interface ShareReceiveResult<T = unknown> {
     host: string;
 }
 export declare class TinyCloudWeb {
+    private openkeySignInInFlight;
+    private prepareSignInToken;
+    private preparedSignIn?;
+    private invalidatePreparedSignIn;
     /** The connected wallet's raw EIP-1193 provider. */
     provider: BrowserProvider;
     /** The normalized EIP-1193 provider used by the SDK. */
@@ -197,6 +210,8 @@ export declare class TinyCloudWeb {
     private _sessionRestoreStatus;
     /** Incremented by signOut; a sign-in that started before it does not complete. */
     private signOutCount;
+    /** The signer set with `setRuntimePermissionSigner`, with the session it was set for. */
+    private runtimeSigner?;
     private signOutInFlight;
     private persistedRestoreBlocked;
     private signOutCleanupFailed;
@@ -348,7 +363,15 @@ export declare class TinyCloudWeb {
     restoreSession(address?: string): Promise<SessionRestoreResult>;
     clearPersistedSession(address?: string): Promise<void>;
     private configuredManifestPermissions;
+    /**
+     * Prepare an OpenKey SIWE before showing an approval button. Call after
+     * OpenKey connect(), then call signIn() from the button's click handler.
+     * A prepared request is single-use and valid for five minutes; call this
+     * method again if the approval button remains visible longer.
+     */
+    prepareSignIn(): Promise<void>;
     signIn: (options?: SignInOptions) => Promise<ClientSession>;
+    private performSignIn;
     /**
      * Sign out: end the session on this instance and clear the persisted
      * session. Afterwards accessors return `undefined` and service calls remain
@@ -446,6 +469,8 @@ export declare class TinyCloudWeb {
      * On approve, this does not mutate the manifest or force a new sign-in.
      * The underlying node creates a secondary delegation to the current
      * session key and records it in the invocation permission map.
+     * Exact current-owner `default/share/<id>` key creation is bound to this
+     * live signed session across consent. Native shells cannot request it.
      *
      * `options.expiryMs` sets the requested lifetime of the issued step-up
      * delegation, in milliseconds. Omitted, the node's default applies. The
@@ -456,6 +481,32 @@ export declare class TinyCloudWeb {
      * `expiryMs` does not apply to them.
      */
     requestPermissions(additional: PermissionEntry[], options?: RequestPermissionsOptions): Promise<RequestPermissionsResult>;
+    /**
+     * Signs the SIWE of a runtime permission grant. Precedence: the signer set with `setRuntimePermissionSigner`, then
+     * the OpenKey client the session was established with (its byte-exact `signMessage`; an OpenKey session's wallet
+     * provider does not implement `personal_sign`), then undefined: the connected wallet signs. Only
+     * `requestPermissions` calls this; sign-in and session setup never do.
+     */
+    private runtimeMessageSigner;
+    /**
+     * Sets the signer for runtime permission grants (`requestPermissions`, and the panel's "allow" buttons), or clears
+     * it with no argument. For apps whose sign-in is not the SDK's OpenKey flow, for example a restored session whose
+     * wallet provider cannot sign: the signer signs each grant's SIWE as an EIP-191 message (`personal_sign`), and the
+     * grant is refused unless the signature recovers to the session's account.
+     *
+     * Call it after the session is established; it throws without one. It is bound to that session: sign-out, a new
+     * sign-in, a restore, or a session for another account clear it. It is never used for sign-in or session setup.
+     * Without it, grants sign through the `openkey` client when configured, else the connected wallet.
+     */
+    setRuntimePermissionSigner(signer?: RuntimePermissionSigner): void;
+    /** True when the panel may ask for a permission: a manifest, a page signer and a live session exist. */
+    private canRequestPanelPermissions;
+    /**
+     * The panel's request for one tab's entry. A grant is kept with the stored session record so it survives a reload;
+     * the entry is not stored when the user signed out while the prompt was open.
+     */
+    private requestPanelPermissions;
+    private runtimeGrantStore;
     getRuntimePermissionDelegations(permissions?: PermissionEntry[]): readonly PortableDelegation[];
     useRuntimeDelegation(delegation: PortableDelegation): Promise<void>;
     useDelegation(delegation: PortableDelegation): Promise<DelegatedAccess>;