@tinycloud/sdk-services 3.8.0-beta.9 → 3.8.1

package/dist/ISQLService-BOgWzHLT.d.cts

@@ -0,0 +1,242 @@
+import { f as Result, c as IService } from './types-CSd0RYir.cjs';
+
+/**
+ * SQL Service Types
+ *
+ * Type definitions for the SQL service operations.
+ */
+/**
+ * Configuration for SQLService.
+ */
+interface SQLServiceConfig {
+    /**
+     * Default database name.
+     * If not set, operations default to "default".
+     */
+    defaultDatabase?: string;
+    /**
+     * Timeout in milliseconds for each SQL request, including reading the
+     * response body. When it elapses the request is aborted and the operation
+     * returns an `ErrorCodes.TIMEOUT` error. Unset (the default), `0`, or
+     * `Infinity` means no timeout.
+     */
+    timeout?: number;
+    /** Allow additional config properties */
+    [key: string]: unknown;
+}
+/**
+ * Options for SQL query operations.
+ */
+interface QueryOptions {
+    /**
+     * Custom abort signal for this operation.
+     */
+    signal?: AbortSignal;
+    /** Maximum rows the node may return. Nodes without limit support ignore it. */
+    maxRows?: number;
+    /** Maximum serialized result bytes the node may return. */
+    maxBytes?: number;
+    /** Redact query failure details before return and ordinary service-error events. */
+    redactErrors?: boolean;
+}
+/**
+ * Options for SQL execute operations.
+ */
+interface ExecuteOptions {
+    /**
+     * Schema initialization statements (CREATE TABLE IF NOT EXISTS ...).
+     * Executed before the main statement on first write.
+     */
+    schema?: string[];
+    /**
+     * Custom abort signal for this operation.
+     */
+    signal?: AbortSignal;
+    /** Redact execute failure details before return and ordinary service-error events. */
+    redactErrors?: boolean;
+}
+/**
+ * Options for SQL batch operations.
+ */
+interface BatchOptions {
+    /**
+     * Custom abort signal for this operation.
+     */
+    signal?: AbortSignal;
+    /** Redact batch failure details before return and ordinary service-error events. */
+    redactErrors?: boolean;
+}
+/**
+ * A SQL value: null, number, string, or binary data.
+ */
+type SqlValue = null | number | string | Uint8Array;
+/**
+ * A SQL statement with optional parameters.
+ */
+interface SqlStatement {
+    sql: string;
+    params?: SqlValue[];
+}
+/**
+ * Response from SQL query operations.
+ */
+interface QueryResponse<T = Record<string, unknown>> {
+    columns: string[];
+    rows: T[][];
+    rowCount: number;
+}
+/**
+ * Response from SQL execute operations.
+ */
+interface ExecuteResponse {
+    changes: number;
+    lastInsertRowId: number | null;
+}
+/**
+ * Response from SQL batch operations.
+ */
+interface BatchResponse {
+    results: ExecuteResponse[];
+}
+/**
+ * A versioned SQL migration owned by an application or SDK subsystem.
+ */
+interface SqlMigration {
+    /**
+     * Stable migration id within the namespace, e.g. "001_initial".
+     */
+    id: string;
+    /**
+     * SQL statements to apply when this migration has not been recorded.
+     * Statements should be idempotent where SQLite supports it.
+     */
+    sql: Array<string | SqlStatement>;
+}
+/**
+ * Options for applying SQL migrations.
+ */
+interface SqlMigrationApplyOptions {
+    /**
+     * Namespace for this migration set, usually an app id or SDK subsystem.
+     */
+    namespace: string;
+    /**
+     * Ordered migration list.
+     */
+    migrations: SqlMigration[];
+    /**
+     * Custom abort signal for migration operations.
+     */
+    signal?: AbortSignal;
+}
+/**
+ * Result from applying SQL migrations.
+ */
+interface SqlMigrationApplyResponse {
+    database: string;
+    namespace: string;
+    status: "already_current" | "applied";
+    applied: string[];
+    skipped: string[];
+}
+/**
+ * SQL service action types.
+ *
+ * URNs derive from the canonical capability registry in `@tinycloud/bootstrap`
+ * (TC-112 single source of truth, vendored from tinycloud-node). `insert`,
+ * `update`, and `delete` were dropped — zero client refs and never accepted
+ * node-side. `select` is a deprecated alias of `read`. `execute`/`export` are
+ * request-kind artifacts, not grantable capabilities: the node routes them by
+ * request-body kind, so they are absent from the registry but kept here as the
+ * invocation ability the client sends today (wire alignment tracked in TC-114).
+ */
+declare const SQLAction: {
+    readonly READ: "tinycloud.sql/read";
+    readonly WRITE: "tinycloud.sql/write";
+    readonly SCHEMA: "tinycloud.sql/schema";
+    readonly ADMIN: "tinycloud.sql/admin";
+    readonly SELECT: "tinycloud.sql/select";
+    readonly EXECUTE: "tinycloud.sql/execute";
+    readonly EXPORT: "tinycloud.sql/export";
+    readonly ALL: "tinycloud.sql/*";
+};
+type SQLActionType = (typeof SQLAction)[keyof typeof SQLAction];
+
+/**
+ * ISQLService - Interface for SQL service.
+ *
+ * Platform-agnostic interface for SQL database operations.
+ */
+
+/**
+ * Migration helper bound to a specific database.
+ */
+interface ISQLMigrations {
+    /**
+     * Apply ordered, app-owned migrations and record completed ids.
+     */
+    apply(options: SqlMigrationApplyOptions): Promise<Result<SqlMigrationApplyResponse>>;
+}
+/**
+ * Database handle interface for operations on a specific named database.
+ */
+interface IDatabaseHandle {
+    /** The database name */
+    readonly name: string;
+    /** Versioned schema migration helper. */
+    readonly migrations: ISQLMigrations;
+    /**
+     * Execute a SQL query and return rows.
+     */
+    query<T = Record<string, unknown>>(sql: string, params?: SqlValue[], options?: QueryOptions): Promise<Result<QueryResponse<T>>>;
+    /**
+     * Execute a SQL statement and return change count.
+     */
+    execute(sql: string, params?: SqlValue[], options?: ExecuteOptions): Promise<Result<ExecuteResponse>>;
+    /**
+     * Execute multiple statements in a transaction.
+     */
+    batch(statements: SqlStatement[], options?: BatchOptions): Promise<Result<BatchResponse>>;
+    /**
+     * Execute a named prepared statement from delegation caveats.
+     */
+    executeStatement(name: string, params?: SqlValue[], options?: QueryOptions): Promise<Result<QueryResponse | ExecuteResponse>>;
+    /**
+     * Export the raw SQLite database file.
+     */
+    export(options?: QueryOptions): Promise<Result<Blob>>;
+}
+/**
+ * SQL service interface.
+ *
+ * Provides SQL database operations with:
+ * - Result type pattern (no throwing)
+ * - Named database handles
+ * - Configurable timeouts
+ * - Abort signal support
+ */
+interface ISQLService extends IService {
+    /**
+     * Get a handle to a named database.
+     * @param name - Database name (defaults to "default")
+     */
+    db(name?: string): IDatabaseHandle;
+    /**
+     * Shortcut: query the default database.
+     */
+    query<T = Record<string, unknown>>(sql: string, params?: SqlValue[], options?: QueryOptions): Promise<Result<QueryResponse<T>>>;
+    /**
+     * Shortcut: execute on the default database.
+     */
+    execute(sql: string, params?: SqlValue[], options?: ExecuteOptions): Promise<Result<ExecuteResponse>>;
+    /**
+     * Shortcut: batch on the default database.
+     */
+    batch(statements: SqlStatement[], options?: BatchOptions): Promise<Result<BatchResponse>>;
+    /**
+     * Service configuration.
+     */
+    readonly config: SQLServiceConfig;
+}
+
+export { type BatchOptions as B, type ExecuteOptions as E, type IDatabaseHandle as I, type QueryOptions as Q, SQLAction as S, type BatchResponse as a, type ExecuteResponse as b, type ISQLMigrations as c, type ISQLService as d, type QueryResponse as e, type SQLActionType as f, type SQLServiceConfig as g, type SqlMigration as h, type SqlMigrationApplyOptions as i, type SqlMigrationApplyResponse as j, type SqlStatement as k, type SqlValue as l };

package/dist/context.d.cts

@@ -1,4 +1,4 @@
-import { I as IServiceContext, a as InvokeFunction, b as InvokeAnyFunction, F as FetchFunction, S as ServiceSession, R as RetryPolicy, T as TelemetryConfig, c as IService, E as EventHandler, d as FetchRequestInit, e as FetchResponse } from './types-DAOyIbXu.cjs';
+import { I as IServiceContext, a as InvokeFunction, b as InvokeAnyFunction, F as FetchFunction, S as ServiceSession, R as RetryPolicy, T as TelemetryConfig, c as IService, E as EventHandler, d as FetchRequestInit, e as FetchResponse } from './types-CSd0RYir.cjs';
 
 /**
  * ServiceContext implementation for TinyCloud SDK Services

package/dist/context.d.ts

@@ -1,4 +1,4 @@
-import { I as IServiceContext, a as InvokeFunction, b as InvokeAnyFunction, F as FetchFunction, S as ServiceSession, R as RetryPolicy, T as TelemetryConfig, c as IService, E as EventHandler, d as FetchRequestInit, e as FetchResponse } from './types-DAOyIbXu.js';
+import { I as IServiceContext, a as InvokeFunction, b as InvokeAnyFunction, F as FetchFunction, S as ServiceSession, R as RetryPolicy, T as TelemetryConfig, c as IService, E as EventHandler, d as FetchRequestInit, e as FetchResponse } from './types-CSd0RYir.js';
 
 /**
  * ServiceContext implementation for TinyCloud SDK Services

package/dist/encryption/index.cjs

@@ -56,6 +56,7 @@ __export(encryption_exports, {
   isNetworkId: () => isNetworkId,
   networkDiscoveryKey: () => networkDiscoveryKey,
   openWrappedKey: () => openWrappedKey,
+  parseEncryptionResource: () => parseEncryptionResource,
   parseNetworkId: () => parseNetworkId,
   utf8Decode: () => utf8Decode,
   utf8Encode: () => utf8Encode,
@@ -201,6 +202,26 @@ function parseNetworkId(networkId) {
   }
   return { networkId, ownerDid, name };
 }
+function parseEncryptionResource(resource) {
+  const networkSeparator = resource.lastIndexOf(":");
+  const nameAndPath = resource.slice(networkSeparator + 1);
+  const pathSeparator = nameAndPath.indexOf("/");
+  const name = pathSeparator === -1 ? nameAndPath : nameAndPath.slice(0, pathSeparator);
+  const networkId = pathSeparator === -1 ? resource : `${resource.slice(0, networkSeparator + 1)}${name}`;
+  const parsed = parseNetworkId(networkId);
+  if (pathSeparator === -1) return parsed;
+  const keyPath = nameAndPath.slice(pathSeparator + 1);
+  const segments = keyPath.split("/");
+  const prefix = keyPath.endsWith("/");
+  if (keyPath.length === 0 || /[\u0000-\u001f\u007f\\]/.test(keyPath) || segments.some(
+    (segment, index) => segment === "." || segment === ".." || segment.length === 0 && !(prefix && index === segments.length - 1)
+  )) {
+    throw new NetworkIdError(
+      `encryption resource has an invalid keyPath (got ${JSON.stringify(resource)})`
+    );
+  }
+  return { ...parsed, keyPath };
+}
 function buildNetworkId(ownerDid, name) {
   if (typeof ownerDid !== "string" || !ownerDid.startsWith("did:")) {
     throw new NetworkIdError("ownerDid must be a DID");
@@ -913,7 +934,12 @@ function ensureNetworkUsableForDecrypt(descriptor) {
 
 // src/encryption/envelope.ts
 function encryptToNetwork(crypto, input) {
-  parseNetworkId(input.networkId);
+  const parsedResource = parseEncryptionResource(
+    input.keyPath === void 0 ? input.networkId : `${input.networkId}/${input.keyPath}`
+  );
+  if (parsedResource.keyPath !== input.keyPath || input.keyPath?.endsWith("/")) {
+    throw new NetworkIdError("keyPath must name an exact encryption key");
+  }
   const alg = input.alg ?? DEFAULT_ENCRYPTION_ALG;
   const keyVersion = input.keyVersion ?? DEFAULT_KEY_VERSION;
   const symmetricKey = crypto.randomBytes(32);
@@ -927,6 +953,7 @@ function encryptToNetwork(crypto, input) {
   const envelope = {
     v: ENVELOPE_VERSION,
     networkId: input.networkId,
+    ...input.keyPath !== void 0 ? { keyPath: input.keyPath } : {},
     alg,
     keyVersion,
     encryptedSymmetricKey,
@@ -958,13 +985,24 @@ function validateEnvelope(crypto, envelope) {
     };
   }
   try {
-    parseNetworkId(e.networkId);
+    if (parseEncryptionResource(e.networkId).keyPath !== void 0) {
+      throw new Error("networkId must identify the network root");
+    }
+    if (e.keyPath !== void 0) {
+      if (typeof e.keyPath !== "string") {
+        throw new Error("keyPath must be a string");
+      }
+      const parsed = parseEncryptionResource(`${e.networkId}/${e.keyPath}`);
+      if (parsed.keyPath !== e.keyPath || e.keyPath.endsWith("/")) {
+        throw new Error("keyPath must name an exact encryption key");
+      }
+    }
   } catch (err2) {
     return {
       ok: false,
       error: encryptionError({
         code: "INVALID_ENVELOPE",
-        message: `envelope.networkId is malformed: ${err2 instanceof Error ? err2.message : String(err2)}`
+        message: `envelope encryption resource is malformed: ${err2 instanceof Error ? err2.message : String(err2)}`
       })
     };
   }
@@ -1037,6 +1075,7 @@ function buildDecryptFacts(input) {
     type: DECRYPT_FACT_TYPE,
     targetNode: input.body.targetNode,
     networkId: input.body.networkId,
+    ...input.body.keyPath !== void 0 ? { keyPath: input.body.keyPath } : {},
     bodyHash,
     encryptedSymmetricKeyHash: input.encryptedSymmetricKeyHash,
     receiverPublicKeyHash,
@@ -1044,10 +1083,14 @@ function buildDecryptFacts(input) {
     keyVersion: input.body.keyVersion
   };
 }
-function buildDecryptAttenuation(networkId) {
-  parseNetworkId(networkId);
+function buildDecryptAttenuation(networkId, keyPath) {
+  const resource = keyPath === void 0 ? networkId : `${networkId}/${keyPath}`;
+  const parsed = parseEncryptionResource(resource);
+  if (parsed.networkId !== networkId || parsed.keyPath !== keyPath || keyPath?.endsWith("/")) {
+    throw new NetworkIdError("keyPath must name an exact encryption key");
+  }
   return {
-    [networkId]: {
+    [resource]: {
       [DECRYPT_ACTION]: {}
     }
   };
@@ -1107,6 +1150,15 @@ function checkDecryptInvocationInput(crypto, input) {
       })
     };
   }
+  if (input.facts.keyPath !== input.body.keyPath) {
+    return {
+      ok: false,
+      error: encryptionError({
+        code: "INVALID_INPUT",
+        message: "facts.keyPath must equal body.keyPath"
+      })
+    };
+  }
   if (input.facts.alg !== input.body.alg) {
     return {
       ok: false,
@@ -1144,7 +1196,9 @@ function checkDecryptInvocationInput(crypto, input) {
     };
   }
   try {
-    parseNetworkId(input.networkId);
+    if (parseEncryptionResource(input.networkId).keyPath !== void 0) {
+      throw new NetworkIdError("networkId must identify the network root");
+    }
   } catch (err2) {
     return {
       ok: false,
@@ -1154,6 +1208,22 @@ function checkDecryptInvocationInput(crypto, input) {
       })
     };
   }
+  try {
+    const resource = parseEncryptionResource(
+      input.body.keyPath === void 0 ? input.body.networkId : `${input.body.networkId}/${input.body.keyPath}`
+    );
+    if (resource.keyPath !== input.body.keyPath || input.body.keyPath?.endsWith("/")) {
+      throw new NetworkIdError("keyPath must name an exact encryption key");
+    }
+  } catch (err2) {
+    return {
+      ok: false,
+      error: encryptionError({
+        code: "INVALID_INPUT",
+        message: err2 instanceof Error ? err2.message : String(err2)
+      })
+    };
+  }
   const canonicalBody = canonicalize(
     input.body
   );
@@ -1394,6 +1464,7 @@ var EncryptionService = class extends BaseService {
         // that spelling in the envelope so a later response can be compared
         // byte-for-byte (notably for checksummed did:pkh principals).
         networkId: descriptor.networkId,
+        ...options?.keyPath !== void 0 ? { keyPath: options.keyPath } : {},
         networkPublicKey,
         plaintext,
         ...options?.aad !== void 0 ? { aad: options.aad } : {},
@@ -1453,6 +1524,7 @@ var EncryptionService = class extends BaseService {
         type: DECRYPT_FACT_TYPE,
         targetNode,
         networkId: envelope.networkId,
+        ...envelope.keyPath !== void 0 ? { keyPath: envelope.keyPath } : {},
         alg: envelope.alg,
         keyVersion: envelope.keyVersion,
         encryptedSymmetricKey: envelope.encryptedSymmetricKey,
@@ -1597,6 +1669,7 @@ var import_decrypt_transport_response_error3 = require("@tinycloud/sdk-services/
   isNetworkId,
   networkDiscoveryKey,
   openWrappedKey,
+  parseEncryptionResource,
   parseNetworkId,
   utf8Decode,
   utf8Encode,