@w3kits/sdk 0.1.0

package/dist/local-cache.js

@@ -0,0 +1,187 @@
+/**
+ * Defines SDK-owned local-first cache model and operation log helpers.
+ * @owner w3kits-sdk
+ * @module sdk
+ * @boundary local-cache
+ */
+export const DB_NAME = "w3kits-local-first-vfs";
+export const DB_VERSION = 2;
+export const OBJECT_STORE = "objects";
+export const BODY_STORE = "bodies";
+export const OPERATION_STORE = "operations";
+export const GENERATION_STORE = "generations";
+export const OPFS_ROOT = "w3kits-local-first-vfs-v1";
+export const OPEN_DB_TIMEOUT_MS = 2500;
+export const DEFAULT_INLINE_BODY_BYTES = 256 * 1024;
+export const DEFAULT_RETRY_BASE_DELAY_MS = 1000;
+export const DEFAULT_MAX_RETRY_DELAY_MS = 30_000;
+/**
+ * Converts local-first body input to a standalone ArrayBuffer.
+ */
+export function toArrayBuffer(body) {
+    if (typeof body === "string")
+        return new TextEncoder().encode(body).buffer;
+    if (body instanceof Uint8Array)
+        return body.buffer.slice(body.byteOffset, body.byteOffset + body.byteLength);
+    return body;
+}
+/**
+ * Normalizes an object key and rejects path escapes/control characters.
+ */
+export function normalizeKey(input, options = {}) {
+    const raw = input.trim().replace(/^\/+/, "").replace(/\/+$/, "");
+    if (!raw) {
+        if (options.allowRoot)
+            return "";
+        throw new Error("invalid_object_key");
+    }
+    const segments = [];
+    for (const segment of raw.split("/")) {
+        if (!segment || segment === ".")
+            continue;
+        if (segment === "..")
+            throw new Error("path_escape");
+        if (/[\u0000-\u001f\u007f\\]/u.test(segment))
+            throw new Error("invalid_object_key");
+        segments.push(segment);
+    }
+    if (segments.length === 0) {
+        if (options.allowRoot)
+            return "";
+        throw new Error("invalid_object_key");
+    }
+    return segments.join("/");
+}
+/**
+ * Builds the local-first cache scope id.
+ */
+export function scopeIdFor(userId, cacheGeneration) {
+    return userId + ":" + cacheGeneration;
+}
+/**
+ * Builds the stable local-first object row id.
+ */
+export function objectId(scopeId, bucket, key) {
+    return scopeId + ":" + bucket + ":" + normalizeKey(key, { allowRoot: true });
+}
+/**
+ * Creates a local operation id.
+ */
+export function createOperationId() {
+    return typeof crypto !== "undefined" && "randomUUID" in crypto
+        ? crypto.randomUUID()
+        : "op-" + Date.now() + "-" + Math.random().toString(36).slice(2);
+}
+/**
+ * Returns the current ISO timestamp for local-first records.
+ */
+export function nowIso() {
+    return new Date().toISOString();
+}
+/**
+ * Computes bounded exponential retry delay for failed local-first operations.
+ */
+export function retryDelayMs(options, attempts) {
+    const base = options.retryBaseDelayMs ?? DEFAULT_RETRY_BASE_DELAY_MS;
+    const max = options.maxRetryDelayMs ?? DEFAULT_MAX_RETRY_DELAY_MS;
+    return Math.min(max, base * 2 ** Math.max(0, attempts - 1));
+}
+/**
+ * Computes the next retry timestamp for a failed local-first operation.
+ */
+export function nextAttemptIso(options, attempts) {
+    return new Date(Date.now() + retryDelayMs(options, attempts)).toISOString();
+}
+/**
+ * Encodes an OPFS-safe path segment.
+ */
+export function safeOpfsSegment(value) {
+    return encodeURIComponent(value).replace(/[!'()*]/g, (char) => "%" + char.charCodeAt(0).toString(16).toUpperCase());
+}
+/**
+ * Decides whether a body should try OPFS storage before IndexedDB storage.
+ */
+export function shouldTryOpfs(options, bodySize) {
+    if (options.bodyStore === "indexeddb")
+        return false;
+    if (options.bodyStore === "opfs")
+        return true;
+    return bodySize > (options.inlineBodyBytes ?? DEFAULT_INLINE_BODY_BYTES);
+}
+/**
+ * Filters local-first objects by scope, bucket, and prefix.
+ */
+export function filterLocalFirstListRows(rows, scopeId, bucket, prefix) {
+    return rows
+        .filter((row) => row.scopeId === scopeId && row.bucket === bucket)
+        .filter((row) => !prefix ||
+        row.key === prefix ||
+        row.key.startsWith(prefix.endsWith("/") ? prefix : prefix + "/"));
+}
+/**
+ * Creates an operation log row with normalized fields.
+ */
+export function createQueuedOperation(input) {
+    const now = input.createdAt ?? nowIso();
+    return {
+        ...input,
+        key: normalizeKey(input.key, { allowRoot: input.type === "mkdir" }),
+        sourceKey: input.sourceKey
+            ? normalizeKey(input.sourceKey, { allowRoot: false })
+            : undefined,
+        operationId: input.operationId ?? createOperationId(),
+        status: input.status ?? "queued",
+        attempts: input.attempts ?? 0,
+        createdAt: now,
+        updatedAt: input.updatedAt ?? now,
+    };
+}
+/**
+ * Marks a queued operation as failed because auth/capability refresh is required.
+ */
+export function markQueuedAuthFailure(operation, options) {
+    const attempts = operation.attempts + 1;
+    const updatedAt = nowIso();
+    return {
+        ...operation,
+        status: "failed",
+        attempts,
+        lastError: "storage_auth_failed",
+        nextAttemptAt: nextAttemptIso(options, attempts),
+        updatedAt,
+    };
+}
+/**
+ * In-memory operation log used by browser tests and non-persistent SDK adapters.
+ */
+export class InMemoryOperationLog {
+    operations = new Map();
+    /**
+     * Enqueues an operation and returns the stored row.
+     */
+    enqueue(input) {
+        const operation = createQueuedOperation(input);
+        this.operations.set(operation.operationId, operation);
+        return operation;
+    }
+    /**
+     * Lists operations that still need remote flush attempts.
+     */
+    pending() {
+        return [...this.operations.values()].filter((operation) => ["queued", "failed"].includes(operation.status));
+    }
+    /**
+     * Replaces one operation row.
+     */
+    update(operation) {
+        this.operations.set(operation.operationId, operation);
+        return operation;
+    }
+    /**
+     * Returns all operations in insertion order.
+     */
+    all() {
+        return [...this.operations.values()];
+    }
+}
+//# sourceMappingURL=local-cache.js.map

package/dist/local-cache.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"local-cache.js","sourceRoot":"","sources":["../src/local-cache.ts"],"names":[],"mappings":"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"}

package/dist/path-mapping.d.ts

@@ -0,0 +1,79 @@
+/**
+ * Defines client-visible path mapping for W3Kits storage capabilities.
+ * @owner w3kits-sdk
+ * @module sdk
+ * @boundary path-mapping
+ * @business Keeps /home/agent file semantics client-owned while Core issues scoped R2 capabilities.
+ */
+export declare const VISIBLE_HOME_ROOT = "/home/agent";
+export declare const APPLICATIONS_ROOT = "/home/agent/Applications";
+export declare const DEFAULT_PROFILE_ID = "default";
+export type StorageScope = {
+    userId: string;
+    profileId?: string | null;
+};
+export type VisiblePathMapping = {
+    userId: string;
+    profileId: string;
+    visiblePath: string;
+    relativeHomePath: string;
+    r2Key: string;
+};
+/**
+ * Represents SDK path and capability validation failures.
+ */
+export declare class W3KitsStorageError extends Error {
+    readonly code: "invalid_user_id" | "invalid_profile_id" | "invalid_plugin_slug" | "invalid_visible_path" | "path_escape" | "outside_visible_root";
+    /**
+     * Initializes a storage error with a stable code.
+     */
+    constructor(code: "invalid_user_id" | "invalid_profile_id" | "invalid_plugin_slug" | "invalid_visible_path" | "path_escape" | "outside_visible_root", message: string);
+}
+/**
+ * Normalizes a Core-authenticated user id for SDK key mapping.
+ */
+export declare function normalizeUserId(userId: string): string;
+/**
+ * Normalizes a selected W3Kits profile id.
+ */
+export declare function normalizeProfileId(profileId?: string | null): string;
+/**
+ * Normalizes plugin slugs used in .app and config roots.
+ */
+export declare function normalizePluginSlug(pluginSlug: string): string;
+/**
+ * Normalizes a root-relative path without allowing escape segments.
+ */
+export declare function normalizeRelativePath(input: string): string;
+/**
+ * Converts a visible /home/agent path to a normalized relative home path.
+ */
+export declare function visiblePathToHomeRelative(visiblePath: string): string;
+/**
+ * Converts a relative home path back to the visible path contract.
+ */
+export declare function homeRelativeToVisiblePath(relativeHomePath: string): string;
+/**
+ * Builds the R2 key for a visible /home/agent path.
+ */
+export declare function visiblePathToR2Key(visiblePath: string, scope: StorageScope): string;
+/**
+ * Returns all mapping components for a visible /home/agent path.
+ */
+export declare function mapVisiblePathToR2(visiblePath: string, scope: StorageScope): VisiblePathMapping;
+/**
+ * Builds a plugin config root under /home/agent.
+ */
+export declare function pluginConfigRoot(pluginSlug: string): string;
+/**
+ * Builds the target .app path for installed plugin launchers.
+ */
+export declare function appFilePath(pluginSlug: string): string;
+/**
+ * Creates a conflict-copy path under the same visible directory.
+ */
+export declare function conflictCopyVisiblePath(visiblePath: string, input?: {
+    label?: string;
+    now?: Date;
+}): string;
+//# sourceMappingURL=path-mapping.d.ts.map

package/dist/path-mapping.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"path-mapping.d.ts","sourceRoot":"","sources":["../src/path-mapping.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,eAAO,MAAM,iBAAiB,gBAAgB,CAAC;AAC/C,eAAO,MAAM,iBAAiB,6BAAsC,CAAC;AACrE,eAAO,MAAM,kBAAkB,YAAY,CAAC;AAI5C,MAAM,MAAM,YAAY,GAAG;IACzB,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC3B,CAAC;AAEF,MAAM,MAAM,kBAAkB,GAAG;IAC/B,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;IACpB,gBAAgB,EAAE,MAAM,CAAC;IACzB,KAAK,EAAE,MAAM,CAAC;CACf,CAAC;AAEF;;GAEG;AACH,qBAAa,kBAAmB,SAAQ,KAAK;aAKzB,IAAI,EAChB,iBAAiB,GACjB,oBAAoB,GACpB,qBAAqB,GACrB,sBAAsB,GACtB,aAAa,GACb,sBAAsB;IAV5B;;OAEG;gBAEe,IAAI,EAChB,iBAAiB,GACjB,oBAAoB,GACpB,qBAAqB,GACrB,sBAAsB,GACtB,aAAa,GACb,sBAAsB,EAC1B,OAAO,EAAE,MAAM;CAKlB;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAMtD;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG,MAAM,CAepE;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,CAS9D;AAED;;GAEG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAqB3D;AAED;;GAEG;AACH,wBAAgB,yBAAyB,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAiBrE;AAED;;GAEG;AACH,wBAAgB,yBAAyB,CAAC,gBAAgB,EAAE,MAAM,GAAG,MAAM,CAG1E;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAChC,WAAW,EAAE,MAAM,EACnB,KAAK,EAAE,YAAY,GAClB,MAAM,CAOR;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAChC,WAAW,EAAE,MAAM,EACnB,KAAK,EAAE,YAAY,GAClB,kBAAkB,CAapB;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,CAE3D;AAED;;GAEG;AACH,wBAAgB,WAAW,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,CAEtD;AAED;;GAEG;AACH,wBAAgB,uBAAuB,CACrC,WAAW,EAAE,MAAM,EACnB,KAAK,GAAE;IAAE,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,GAAG,CAAC,EAAE,IAAI,CAAA;CAAO,GACzC,MAAM,CAcR"}

package/dist/path-mapping.js

@@ -0,0 +1,156 @@
+/**
+ * Defines client-visible path mapping for W3Kits storage capabilities.
+ * @owner w3kits-sdk
+ * @module sdk
+ * @boundary path-mapping
+ * @business Keeps /home/agent file semantics client-owned while Core issues scoped R2 capabilities.
+ */
+export const VISIBLE_HOME_ROOT = "/home/agent";
+export const APPLICATIONS_ROOT = `${VISIBLE_HOME_ROOT}/Applications`;
+export const DEFAULT_PROFILE_ID = "default";
+const CONTROL_CHARS = /[\u0000-\u001f\u007f]/u;
+/**
+ * Represents SDK path and capability validation failures.
+ */
+export class W3KitsStorageError extends Error {
+    code;
+    /**
+     * Initializes a storage error with a stable code.
+     */
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = "W3KitsStorageError";
+    }
+}
+/**
+ * Normalizes a Core-authenticated user id for SDK key mapping.
+ */
+export function normalizeUserId(userId) {
+    const normalized = userId.trim();
+    if (!/^[A-Za-z0-9._:@-]+$/u.test(normalized)) {
+        throw new W3KitsStorageError("invalid_user_id", "Invalid user id");
+    }
+    return normalized;
+}
+/**
+ * Normalizes a selected W3Kits profile id.
+ */
+export function normalizeProfileId(profileId) {
+    const normalized = (profileId || DEFAULT_PROFILE_ID).trim();
+    if (!/^[a-z0-9][a-z0-9._-]{0,62}$/u.test(normalized)) {
+        throw new W3KitsStorageError("invalid_profile_id", "Invalid profile id");
+    }
+    if (normalized === "." || normalized === "..") {
+        throw new W3KitsStorageError("invalid_profile_id", "Invalid profile id");
+    }
+    return normalized;
+}
+/**
+ * Normalizes plugin slugs used in .app and config roots.
+ */
+export function normalizePluginSlug(pluginSlug) {
+    const normalized = pluginSlug.trim();
+    if (!/^[a-z0-9][a-z0-9._-]{0,127}$/u.test(normalized)) {
+        throw new W3KitsStorageError("invalid_plugin_slug", "Invalid plugin slug");
+    }
+    return normalized;
+}
+/**
+ * Normalizes a root-relative path without allowing escape segments.
+ */
+export function normalizeRelativePath(input) {
+    const raw = input.trim().replace(/\\/g, "/").replace(/^\/+/, "");
+    if (CONTROL_CHARS.test(raw)) {
+        throw new W3KitsStorageError("invalid_visible_path", "Visible path contains unsupported characters");
+    }
+    const segments = [];
+    for (const segment of raw.split("/")) {
+        if (!segment || segment === ".")
+            continue;
+        if (segment === "..") {
+            throw new W3KitsStorageError("path_escape", "Visible path cannot escape its root");
+        }
+        segments.push(segment);
+    }
+    return segments.join("/");
+}
+/**
+ * Converts a visible /home/agent path to a normalized relative home path.
+ */
+export function visiblePathToHomeRelative(visiblePath) {
+    const raw = visiblePath.trim().replace(/\\/g, "/").replace(/\/+$/u, "");
+    if (raw === "" ||
+        raw === "/" ||
+        raw === "/home" ||
+        raw === VISIBLE_HOME_ROOT) {
+        return "";
+    }
+    if (!raw.startsWith(`${VISIBLE_HOME_ROOT}/`)) {
+        throw new W3KitsStorageError("outside_visible_root", `Visible path must be under ${VISIBLE_HOME_ROOT}`);
+    }
+    return normalizeRelativePath(raw.slice(`${VISIBLE_HOME_ROOT}/`.length));
+}
+/**
+ * Converts a relative home path back to the visible path contract.
+ */
+export function homeRelativeToVisiblePath(relativeHomePath) {
+    const relative = normalizeRelativePath(relativeHomePath);
+    return relative ? `${VISIBLE_HOME_ROOT}/${relative}` : VISIBLE_HOME_ROOT;
+}
+/**
+ * Builds the R2 key for a visible /home/agent path.
+ */
+export function visiblePathToR2Key(visiblePath, scope) {
+    const userId = normalizeUserId(scope.userId);
+    const profileId = normalizeProfileId(scope.profileId);
+    const relativeHomePath = visiblePathToHomeRelative(visiblePath);
+    return ["users", userId, "profiles", profileId, "home", relativeHomePath]
+        .filter((segment) => segment !== "")
+        .join("/");
+}
+/**
+ * Returns all mapping components for a visible /home/agent path.
+ */
+export function mapVisiblePathToR2(visiblePath, scope) {
+    const userId = normalizeUserId(scope.userId);
+    const profileId = normalizeProfileId(scope.profileId);
+    const relativeHomePath = visiblePathToHomeRelative(visiblePath);
+    return {
+        userId,
+        profileId,
+        visiblePath: homeRelativeToVisiblePath(relativeHomePath),
+        relativeHomePath,
+        r2Key: ["users", userId, "profiles", profileId, "home", relativeHomePath]
+            .filter((segment) => segment !== "")
+            .join("/"),
+    };
+}
+/**
+ * Builds a plugin config root under /home/agent.
+ */
+export function pluginConfigRoot(pluginSlug) {
+    return `${VISIBLE_HOME_ROOT}/.config/${normalizePluginSlug(pluginSlug)}`;
+}
+/**
+ * Builds the target .app path for installed plugin launchers.
+ */
+export function appFilePath(pluginSlug) {
+    return `${APPLICATIONS_ROOT}/${normalizePluginSlug(pluginSlug)}.app`;
+}
+/**
+ * Creates a conflict-copy path under the same visible directory.
+ */
+export function conflictCopyVisiblePath(visiblePath, input = {}) {
+    const normalized = homeRelativeToVisiblePath(visiblePathToHomeRelative(visiblePath));
+    const slash = normalized.lastIndexOf("/");
+    const directory = slash >= 0 ? normalized.slice(0, slash) : VISIBLE_HOME_ROOT;
+    const filename = slash >= 0 ? normalized.slice(slash + 1) : normalized;
+    const dot = filename.lastIndexOf(".");
+    const stem = dot > 0 ? filename.slice(0, dot) : filename;
+    const extension = dot > 0 ? filename.slice(dot) : "";
+    const stamp = input.label ??
+        (input.now ?? new Date()).toISOString().replace(/[:.]/g, "-");
+    return `${directory}/${stem}.conflict-${stamp}${extension}`;
+}
+//# sourceMappingURL=path-mapping.js.map

package/dist/path-mapping.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"path-mapping.js","sourceRoot":"","sources":["../src/path-mapping.ts"],"names":[],"mappings":"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"}

package/dist/plugin.d.ts

@@ -0,0 +1,34 @@
+import { type R2DataPlaneDescriptor, type W3KitsStorageCapabilityDescriptor } from "./r2-client.js";
+export * from "./path-mapping.js";
+export * from "./local-cache.js";
+export * from "./app-file.js";
+export * from "./storage/index.js";
+export * from "./r2-client.js";
+export type W3KitsPluginStorage = {
+    descriptor: W3KitsStorageCapabilityDescriptor;
+    visibleRoot: W3KitsStorageCapabilityDescriptor["visibleRoot"];
+    capability: W3KitsStorageCapabilityDescriptor["capability"];
+    r2: R2DataPlaneDescriptor;
+    authHeader: "x-w3kits-runtime-session";
+    localFirst: W3KitsStorageCapabilityDescriptor["localFirst"];
+    r2KeyForVisiblePath(visiblePath: string): string;
+};
+export type InitializeW3KitsPluginStorageInput = {
+    descriptor: unknown;
+    expectedPluginSlug?: string;
+};
+/**
+ * Represents plugin storage descriptor validation failures.
+ */
+export declare class W3KitsPluginStorageError extends Error {
+    readonly code: "legacy_storage_descriptor" | "invalid_storage_descriptor" | "invalid_storage_descriptor_version" | "legacy_fake_credentials" | "permanent_r2_credentials" | "descriptor_scope_mismatch" | "path_outside_capability";
+    /**
+     * Initializes a plugin storage error with a stable code.
+     */
+    constructor(code: "legacy_storage_descriptor" | "invalid_storage_descriptor" | "invalid_storage_descriptor_version" | "legacy_fake_credentials" | "permanent_r2_credentials" | "descriptor_scope_mismatch" | "path_outside_capability", message: string);
+}
+/**
+ * Validates and initializes the plugin storage bridge from a Core-issued descriptor.
+ */
+export declare function initializeW3KitsPluginStorage(input: InitializeW3KitsPluginStorageInput): W3KitsPluginStorage;
+//# sourceMappingURL=plugin.d.ts.map

package/dist/plugin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin.d.ts","sourceRoot":"","sources":["../src/plugin.ts"],"names":[],"mappings":"AASA,OAAO,EAEL,KAAK,qBAAqB,EAC1B,KAAK,iCAAiC,EACvC,MAAM,gBAAgB,CAAC;AAIxB,cAAc,mBAAmB,CAAC;AAClC,cAAc,kBAAkB,CAAC;AACjC,cAAc,eAAe,CAAC;AAC9B,cAAc,oBAAoB,CAAC;AACnC,cAAc,gBAAgB,CAAC;AAE/B,MAAM,MAAM,mBAAmB,GAAG;IAChC,UAAU,EAAE,iCAAiC,CAAC;IAC9C,WAAW,EAAE,iCAAiC,CAAC,aAAa,CAAC,CAAC;IAC9D,UAAU,EAAE,iCAAiC,CAAC,YAAY,CAAC,CAAC;IAC5D,EAAE,EAAE,qBAAqB,CAAC;IAC1B,UAAU,EAAE,0BAA0B,CAAC;IACvC,UAAU,EAAE,iCAAiC,CAAC,YAAY,CAAC,CAAC;IAC5D,mBAAmB,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAAC;CAClD,CAAC;AAEF,MAAM,MAAM,kCAAkC,GAAG;IAC/C,UAAU,EAAE,OAAO,CAAC;IACpB,kBAAkB,CAAC,EAAE,MAAM,CAAC;CAC7B,CAAC;AAEF;;GAEG;AACH,qBAAa,wBAAyB,SAAQ,KAAK;aAK/B,IAAI,EAChB,2BAA2B,GAC3B,4BAA4B,GAC5B,oCAAoC,GACpC,yBAAyB,GACzB,0BAA0B,GAC1B,2BAA2B,GAC3B,yBAAyB;IAX/B;;OAEG;gBAEe,IAAI,EAChB,2BAA2B,GAC3B,4BAA4B,GAC5B,oCAAoC,GACpC,yBAAyB,GACzB,0BAA0B,GAC1B,2BAA2B,GAC3B,yBAAyB,EAC7B,OAAO,EAAE,MAAM;CAKlB;AAED;;GAEG;AACH,wBAAgB,6BAA6B,CAC3C,KAAK,EAAE,kCAAkC,GACxC,mBAAmB,CA0CrB"}

package/dist/plugin.js

@@ -0,0 +1,124 @@
+/**
+ * Plugin SDK entrypoint.
+ * @owner w3kits-sdk
+ * @module sdk
+ */
+import { mapVisiblePathToR2, pluginConfigRoot, } from "./path-mapping.js";
+import { W3KITS_STORAGE_CAPABILITY_DESCRIPTOR_VERSION, } from "./r2-client.js";
+const LEGACY_OBJECT_FACADE_PATH = `/${["api", "vfs", "objects"].join("/")}`;
+export * from "./path-mapping.js";
+export * from "./local-cache.js";
+export * from "./app-file.js";
+export * from "./storage/index.js";
+export * from "./r2-client.js";
+/**
+ * Represents plugin storage descriptor validation failures.
+ */
+export class W3KitsPluginStorageError extends Error {
+    code;
+    /**
+     * Initializes a plugin storage error with a stable code.
+     */
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = "W3KitsPluginStorageError";
+    }
+}
+/**
+ * Validates and initializes the plugin storage bridge from a Core-issued descriptor.
+ */
+export function initializeW3KitsPluginStorage(input) {
+    const descriptor = assertW3KitsStorageCapabilityDescriptor(input.descriptor);
+    if (input.expectedPluginSlug &&
+        descriptor.visibleRoot !== pluginConfigRoot(input.expectedPluginSlug)) {
+        throw new W3KitsPluginStorageError("descriptor_scope_mismatch", "Plugin storage descriptor is not scoped to this plugin config root");
+    }
+    const expectedPrefix = mapVisiblePathToR2(descriptor.visibleRoot, {
+        userId: descriptor.capability.userId,
+        profileId: descriptor.capability.profileId,
+    }).r2Key;
+    if (descriptor.r2.prefix !== expectedPrefix) {
+        throw new W3KitsPluginStorageError("descriptor_scope_mismatch", "Plugin storage descriptor R2 prefix does not match its visible root");
+    }
+    return {
+        descriptor,
+        visibleRoot: descriptor.visibleRoot,
+        capability: descriptor.capability,
+        r2: descriptor.r2,
+        authHeader: descriptor.auth.header,
+        localFirst: descriptor.localFirst,
+        r2KeyForVisiblePath(visiblePath) {
+            const mapping = mapVisiblePathToR2(visiblePath, descriptor.capability);
+            if (!r2KeyWithinPrefix(mapping.r2Key, descriptor.r2.prefix)) {
+                throw new W3KitsPluginStorageError("path_outside_capability", "Visible path is outside the plugin storage capability");
+            }
+            return mapping.r2Key;
+        },
+    };
+}
+/**
+ * Asserts that an unknown value is a current SDK storage capability descriptor.
+ */
+function assertW3KitsStorageCapabilityDescriptor(value) {
+    const descriptor = record(value, "invalid_storage_descriptor");
+    if (descriptor.type === "w3kits-vfs-object-facade" ||
+        descriptor.endpoint === LEGACY_OBJECT_FACADE_PATH) {
+        throw new W3KitsPluginStorageError("legacy_storage_descriptor", "Legacy VFS object-facade descriptors are not accepted by the SDK plugin bridge");
+    }
+    if (descriptor.version !== W3KITS_STORAGE_CAPABILITY_DESCRIPTOR_VERSION) {
+        throw new W3KitsPluginStorageError("invalid_storage_descriptor_version", "Unsupported W3Kits storage descriptor version");
+    }
+    const capability = record(descriptor.capability, "invalid_storage_descriptor");
+    const r2 = record(descriptor.r2, "invalid_storage_descriptor");
+    const auth = record(descriptor.auth, "invalid_storage_descriptor");
+    const localFirst = record(descriptor.localFirst, "invalid_storage_descriptor");
+    if (typeof descriptor.visibleRoot !== "string" ||
+        descriptor.visibleRoot !== capability.root ||
+        typeof capability.userId !== "string" ||
+        typeof capability.profileId !== "string" ||
+        !Array.isArray(capability.actions) ||
+        typeof capability.expiresAt !== "string" ||
+        typeof capability.credentialMode !== "string" ||
+        typeof r2.bucket !== "string" ||
+        typeof r2.endpoint !== "string" ||
+        r2.region !== "auto" ||
+        r2.forcePathStyle !== true ||
+        typeof r2.prefix !== "string" ||
+        !Array.isArray(r2.actions) ||
+        auth.mode !== "runtime-session" ||
+        auth.header !== "x-w3kits-runtime-session" ||
+        typeof localFirst.enabled !== "boolean") {
+        throw new W3KitsPluginStorageError("invalid_storage_descriptor", "Invalid W3Kits storage capability descriptor");
+    }
+    if (r2.credentials !== undefined) {
+        const credentials = record(r2.credentials, "invalid_storage_descriptor");
+        if (credentials.accessKeyId === "w3kits" ||
+            credentials.secretAccessKey === "w3kits-runtime-session") {
+            throw new W3KitsPluginStorageError("legacy_fake_credentials", "Legacy fake S3 credentials are not accepted by the SDK plugin bridge");
+        }
+        if (typeof credentials.accessKeyId !== "string" ||
+            typeof credentials.secretAccessKey !== "string" ||
+            typeof credentials.expiresAt !== "string") {
+            throw new W3KitsPluginStorageError("permanent_r2_credentials", "Plugin storage descriptors may only include expiring R2 credentials");
+        }
+    }
+    return descriptor;
+}
+/**
+ * Narrows an unknown descriptor fragment to a non-array object.
+ */
+function record(value, code) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        throw new W3KitsPluginStorageError(code, "Invalid W3Kits plugin storage descriptor");
+    }
+    return value;
+}
+/**
+ * Checks whether a mapped R2 key remains inside the descriptor prefix.
+ */
+function r2KeyWithinPrefix(key, prefix) {
+    const cleanPrefix = prefix.replace(/\/+$/u, "");
+    return key === cleanPrefix || key.startsWith(`${cleanPrefix}/`);
+}
+//# sourceMappingURL=plugin.js.map

package/dist/plugin.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin.js","sourceRoot":"","sources":["../src/plugin.ts"],"names":[],"mappings":"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"}