@hiai-gg/docsmint 0.3.5 → 0.3.7

package/dist/lifecycle-persistent.d.ts

@@ -0,0 +1,31 @@
+import { type AssertPurgeAllowed, type LifecycleHostStep, type UserDataLifecycle, type UserDataLifecycleAdapter } from "./lifecycle";
+/**
+ * Minimal transaction boundary required by the durable lifecycle runtime.
+ * Hosts supply a request/RLS-scoped executor; SDK code never imports a global
+ * database singleton or bypasses host tenant policy.
+ */
+export type LifecycleScopedDatabaseExecutor = <T>(context: Readonly<{
+    actorUserId: string;
+    requestId: string;
+    signal?: AbortSignal;
+}>, operation: () => Promise<T>) => Promise<T>;
+/**
+ * Public persistent lifecycle composition contract.  The OSS persistence
+ * saga is supplied by the backend runtime; SaaS hosts attach their own steps
+ * and RLS executor without private imports.
+ */
+export type LifecycleRuntimeAdapters = Readonly<{
+    database: LifecycleScopedDatabaseExecutor;
+    adapter: UserDataLifecycleAdapter;
+}>;
+export type PersistentLifecycleRuntimeOptions = Readonly<{
+    runtime: LifecycleRuntimeAdapters;
+    assertPurgeAllowed: AssertPurgeAllowed;
+    hostSteps?: readonly LifecycleHostStep[];
+}>;
+/**
+ * Creates an immutable, transaction-scoped public lifecycle facade.
+ * The database executor is invoked for every OSS adapter operation so hosts
+ * can set RLS GUCs and reject a missing scope before any mutation occurs.
+ */
+export declare function createPersistentLifecycleRuntime(options: PersistentLifecycleRuntimeOptions): UserDataLifecycle;

package/dist/lifecycle-persistent.js

@@ -0,0 +1,33 @@
+import { createUserDataLifecycle, orderLifecycleHostSteps, } from "./lifecycle";
+function immutableContext(context) {
+    return Object.freeze({ ...context });
+}
+/**
+ * Creates an immutable, transaction-scoped public lifecycle facade.
+ * The database executor is invoked for every OSS adapter operation so hosts
+ * can set RLS GUCs and reject a missing scope before any mutation occurs.
+ */
+export function createPersistentLifecycleRuntime(options) {
+    const hostSteps = orderLifecycleHostSteps(options.hostSteps ?? []);
+    const lifecycle = createUserDataLifecycle({
+        async *exportUserData(context) {
+            const immutable = immutableContext(context);
+            const records = await options.runtime.database(immutable, async () => {
+                const result = [];
+                for await (const record of options.runtime.adapter.exportUserData(immutable))
+                    result.push(record);
+                return result;
+            });
+            for (const record of records)
+                yield record;
+        },
+        async purgeUserData(context, gate) {
+            const immutable = immutableContext(context);
+            return options.runtime.database(immutable, () => options.runtime.adapter.purgeUserData(immutable, gate));
+        },
+    }, async (context) => options.assertPurgeAllowed(immutableContext(context)));
+    // Validate host-step ordering eagerly. The OSS adapter owns invocation; the
+    // public factory records the accepted contract without inventing SaaS data.
+    void hostSteps;
+    return lifecycle;
+}

package/dist/server-only-browser-entry.js

@@ -0,0 +1,3 @@
+"use strict";
+/** Browser-condition guard for every server-only public subpath. */
+throw new Error("This @hiai-gg/docsmint entrypoint is server-only");

package/dist/storage-quota.d.ts

@@ -46,6 +46,42 @@ export type StorageQuotaService = Readonly<{
     commit(request: StorageQuotaCommitRequest): Promise<StorageQuotaCommitResult>;
     release(request: StorageQuotaReleaseRequest): Promise<StorageQuotaReleaseResult>;
 }>;
+/**
+ * Verified server-side identity for an attachment write.  It is intentionally
+ * richer than the generic quota adapter: attachment storage must be charged
+ * to one workspace, actor and immutable object key before a presign is issued.
+ */
+export type AttachmentStorageQuotaContext = Readonly<{
+    workspaceId: string;
+    actorUserId: string;
+    documentId: string;
+    storageKey: string;
+    proposedSize: number;
+    requestId: string;
+    idempotencyKey: string;
+    signal?: AbortSignal;
+}>;
+export type AttachmentStorageQuotaFinalization = Readonly<{
+    reservationId: string;
+    actualSize: number;
+}>;
+/**
+ * OSS invokes this only after it has verified tenant context and document
+ * access.  A host provider is never exposed to HTTP or browser code.
+ */
+export type AttachmentStorageQuotaAdmission = Readonly<{
+    reserve(context: AttachmentStorageQuotaContext): Promise<Readonly<{
+        id: string;
+    }>>;
+    finalize(context: AttachmentStorageQuotaContext, finalization: AttachmentStorageQuotaFinalization): Promise<void>;
+    releaseReservation(context: AttachmentStorageQuotaContext, reservationId: string): Promise<void>;
+    releaseCommitted(context: AttachmentStorageQuotaContext): Promise<void>;
+}>;
+export declare class MissingAttachmentStorageQuotaAdmissionError extends Error {
+    readonly code: "ATTACHMENT_STORAGE_QUOTA_ADMISSION_MISSING";
+    constructor();
+}
+export declare function requireAttachmentStorageQuotaAdmission(admission: AttachmentStorageQuotaAdmission | undefined): AttachmentStorageQuotaAdmission;
 export declare class StorageQuotaExceededError extends Error {
     readonly code: "STORAGE_QUOTA_EXCEEDED";
     readonly usageBytes: number;

package/dist/storage-quota.js

@@ -1,4 +1,16 @@
 /** Server-only, persistence-agnostic storage quota contract. */
+export class MissingAttachmentStorageQuotaAdmissionError extends Error {
+    code = "ATTACHMENT_STORAGE_QUOTA_ADMISSION_MISSING";
+    constructor() {
+        super("Attachment storage quota admission is required when workspace tenancy is enabled");
+        this.name = "MissingAttachmentStorageQuotaAdmissionError";
+    }
+}
+export function requireAttachmentStorageQuotaAdmission(admission) {
+    if (!admission)
+        throw new MissingAttachmentStorageQuotaAdmissionError();
+    return admission;
+}
 export class StorageQuotaExceededError extends Error {
     code = "STORAGE_QUOTA_EXCEEDED";
     usageBytes;
@@ -71,7 +83,8 @@ export function createStorageQuotaService(adapter) {
             assertReservationId(request.reservationId);
             assertPositiveBytes(request.actualBytes, "actualBytes");
             const result = await adapter.commit(Object.freeze({ ...request }));
-            if (result.status !== "committed" && result.status !== "already_committed") {
+            if (result.status !== "committed" &&
+                result.status !== "already_committed") {
                 throw new TypeError("Storage quota adapter returned an invalid commit status");
             }
             return Object.freeze({ ...result });

package/dist/types.d.ts

@@ -294,11 +294,18 @@ export interface DocsAttachmentPresignInput {
 export interface DocsAttachmentPresignResponse {
     url: string;
     key: string;
+    /**
+     * Opaque server-issued reservation. Present only when workspace storage
+     * enforcement is enabled and required verbatim by confirmAttachment.
+     */
+    quotaReservationId?: string;
     maxSize: number;
     expiresIn: number;
 }
 export interface DocsAttachmentConfirmInput extends DocsAttachmentPresignInput {
     key: string;
+    /** The opaque reservation returned by presignAttachment when present. */
+    quotaReservationId?: string;
 }
 export type DocsApiKeyScope = "global" | `category:${string}:${"read" | "edit" | "write"}`;
 export interface DocsApiKeyCreated {

package/dist/workspace.d.ts

@@ -15,7 +15,10 @@ export type WorkspaceAssertionOptions = Readonly<{
     issuer: string;
     nowSeconds?: number;
     clockSkewSeconds?: number;
-    maxTtlSeconds?: number;
+    /** @deprecated Assertion lifetime is fixed at 60 seconds. */
+    maxTtlSeconds?: never;
 }>;
+export declare const DOCSMINT_WORKSPACE_ASSERTION_TTL_SECONDS = 60;
+export declare const DOCSMINT_WORKSPACE_ASSERTION_CLOCK_SKEW_SECONDS = 5;
 export declare function createDocsmintWorkspaceAssertion(context: DocsmintWorkspaceContext, secret: string): Promise<string>;
 export declare function verifyDocsmintWorkspaceAssertion(assertion: string, options: WorkspaceAssertionOptions): Promise<DocsmintWorkspaceContext>;

package/dist/workspace.js

@@ -4,17 +4,22 @@ export const DOCSMINT_WORKSPACE_CONTEXT_HEADER = "x-docsmint-workspace-context";
 export const EXTERNAL_TENANT_CONTEXT_HEADER = "x-hiai-tenant-context";
 const encoder = new TextEncoder();
 const decoder = new TextDecoder();
-const MAX_TTL_SECONDS = 300;
+export const DOCSMINT_WORKSPACE_ASSERTION_TTL_SECONDS = 60;
+export const DOCSMINT_WORKSPACE_ASSERTION_CLOCK_SKEW_SECONDS = 5;
 function toBase64Url(bytes) {
     let binary = "";
     for (const byte of bytes)
         binary += String.fromCharCode(byte);
-    return btoa(binary).replaceAll("+", "-").replaceAll("/", "_").replace(/=+$/, "");
+    return btoa(binary)
+        .replaceAll("+", "-")
+        .replaceAll("/", "_")
+        .replace(/=+$/, "");
 }
 function fromBase64Url(value) {
     if (!/^[A-Za-z0-9_-]+$/.test(value))
         throw new Error("Invalid base64url");
-    const padded = value.replaceAll("-", "+").replaceAll("_", "/") + "=".repeat((4 - (value.length % 4)) % 4);
+    const padded = value.replaceAll("-", "+").replaceAll("_", "/") +
+        "=".repeat((4 - (value.length % 4)) % 4);
     const binary = atob(padded);
     return Uint8Array.from(binary, (character) => character.charCodeAt(0));
 }
@@ -26,13 +31,20 @@ function assertContext(value) {
     if (!value || typeof value !== "object")
         throw new Error("Invalid workspace assertion payload");
     const context = value;
-    if (typeof context.actorUserId !== "string" || !/^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(context.actorUserId))
+    if (typeof context.actorUserId !== "string" ||
+        !/^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(context.actorUserId))
         throw new Error("Invalid actorUserId");
-    if (typeof context.workspaceId !== "string" || !context.workspaceId.trim() || context.workspaceId.trim() !== context.workspaceId || context.workspaceId.length > 128)
+    if (typeof context.workspaceId !== "string" ||
+        !context.workspaceId.trim() ||
+        context.workspaceId.trim() !== context.workspaceId ||
+        context.workspaceId.length > 128)
         throw new Error("Invalid workspaceId");
     if (!["owner", "admin", "editor", "viewer"].includes(context.actorRole))
         throw new Error("Invalid actorRole");
-    if (!Number.isFinite(context.issuedAt) || !Number.isFinite(context.expiresAt) || typeof context.issuer !== "string" || !context.issuer)
+    if (!Number.isFinite(context.issuedAt) ||
+        !Number.isFinite(context.expiresAt) ||
+        typeof context.issuer !== "string" ||
+        !context.issuer)
         throw new Error("Invalid workspace assertion timestamps or issuer");
 }
 export async function createDocsmintWorkspaceAssertion(context, secret) {
@@ -59,8 +71,17 @@ export async function verifyDocsmintWorkspaceAssertion(assertion, options) {
     if (context.issuer !== options.issuer)
         throw new Error("Invalid workspace assertion issuer");
     const now = options.nowSeconds ?? Math.floor(Date.now() / 1000);
-    const skew = options.clockSkewSeconds ?? 5;
-    if (context.issuedAt > now + skew || context.expiresAt <= now - skew || context.expiresAt <= context.issuedAt || context.expiresAt - context.issuedAt > (options.maxTtlSeconds ?? MAX_TTL_SECONDS))
+    const skew = options.clockSkewSeconds ?? DOCSMINT_WORKSPACE_ASSERTION_CLOCK_SKEW_SECONDS;
+    if (!Number.isSafeInteger(skew) ||
+        skew < 0 ||
+        skew > DOCSMINT_WORKSPACE_ASSERTION_CLOCK_SKEW_SECONDS) {
+        throw new Error("Invalid workspace assertion clock skew");
+    }
+    if (context.issuedAt > now + skew ||
+        context.expiresAt <= now - skew ||
+        context.expiresAt <= context.issuedAt ||
+        context.expiresAt - context.issuedAt >
+            DOCSMINT_WORKSPACE_ASSERTION_TTL_SECONDS)
         throw new Error("Invalid workspace assertion lifetime");
     return Object.freeze({ ...context });
 }

package/package.json

@@ -1,10 +1,11 @@
 {
   "name": "@hiai-gg/docsmint",
-  "version": "0.3.5",
+  "version": "0.3.7",
   "type": "module",
   "browser": {
     "./dist/backend-launcher.js": false,
     "./dist/lifecycle.js": false,
+    "./dist/lifecycle-persistent.js": false,
     "./dist/storage-quota.js": false,
     "./dist/workspace.js": false
   },
@@ -109,6 +110,86 @@
       "import": "./dist/frontend/api/settings.js",
       "types": "./dist/frontend/api/settings.d.ts"
     },
+    "./frontend/api/attachments": {
+      "import": "./dist/frontend/api/attachments.js",
+      "types": "./dist/frontend/api/attachments.d.ts"
+    },
+    "./frontend/collaboration": {
+      "import": "./dist/frontend/collaboration.js",
+      "types": "./dist/frontend/collaboration.d.ts"
+    },
+    "./frontend/components/create-snapshot-dialog": {
+      "import": "./dist/frontend/components/create-snapshot-dialog.js",
+      "types": "./dist/frontend/components/create-snapshot-dialog.d.ts"
+    },
+    "./frontend/components/delete-dialog": {
+      "import": "./dist/frontend/components/delete-dialog.js",
+      "types": "./dist/frontend/components/delete-dialog.d.ts"
+    },
+    "./frontend/components/category-dialog": {
+      "import": "./dist/frontend/components/category-dialog.js",
+      "types": "./dist/frontend/components/category-dialog.d.ts"
+    },
+    "./frontend/components/folder-node": {
+      "import": "./dist/frontend/components/folder-node.js",
+      "types": "./dist/frontend/components/folder-node.d.ts"
+    },
+    "./frontend/document-drop-coordinator": {
+      "import": "./dist/frontend/document-drop-coordinator.js",
+      "types": "./dist/frontend/document-drop-coordinator.d.ts"
+    },
+    "./frontend/offline/identity": {
+      "import": "./dist/frontend/offline/identity.js",
+      "types": "./dist/frontend/offline/identity.d.ts"
+    },
+    "./frontend/doc-tabs": {
+      "import": "./dist/frontend/doc-tabs.js",
+      "types": "./dist/frontend/doc-tabs.d.ts"
+    },
+    "./frontend/components/editor/document-editor": {
+      "import": "./dist/frontend/components/editor/document-editor.js",
+      "types": "./dist/frontend/components/editor/document-editor.d.ts"
+    },
+    "./frontend/components/folder-tree-selector": {
+      "import": "./dist/frontend/components/folder-tree-selector.js",
+      "types": "./dist/frontend/components/folder-tree-selector.d.ts"
+    },
+    "./frontend/components/save-as-dialog": {
+      "import": "./dist/frontend/components/save-as-dialog.js",
+      "types": "./dist/frontend/components/save-as-dialog.d.ts"
+    },
+    "./frontend/components/share-dialog": {
+      "import": "./dist/frontend/components/share-dialog.js",
+      "types": "./dist/frontend/components/share-dialog.d.ts"
+    },
+    "./frontend/components/tag-create-dialog": {
+      "import": "./dist/frontend/components/tag-create-dialog.js",
+      "types": "./dist/frontend/components/tag-create-dialog.d.ts"
+    },
+    "./frontend/components/version-history": {
+      "import": "./dist/frontend/components/version-history.js",
+      "types": "./dist/frontend/components/version-history.d.ts"
+    },
+    "./frontend/components/editor/document-title": {
+      "import": "./dist/frontend/components/editor/document-title.js",
+      "types": "./dist/frontend/components/editor/document-title.d.ts"
+    },
+    "./frontend/components/editor/markdown-toggle": {
+      "import": "./dist/frontend/components/editor/markdown-toggle.js",
+      "types": "./dist/frontend/components/editor/markdown-toggle.d.ts"
+    },
+    "./frontend/components/editor/extensions": {
+      "import": "./dist/frontend/components/editor/extensions.js",
+      "types": "./dist/frontend/components/editor/extensions.d.ts"
+    },
+    "./frontend/components/editor/markdown": {
+      "import": "./dist/frontend/components/editor/markdown.js",
+      "types": "./dist/frontend/components/editor/markdown.d.ts"
+    },
+    "./frontend/components/editor/docx-serializer": {
+      "import": "./dist/frontend/components/editor/docx-serializer.js",
+      "types": "./dist/frontend/components/editor/docx-serializer.d.ts"
+    },
     "./frontend/components/sidebar": {
       "import": "./dist/frontend/components/sidebar.js",
       "types": "./dist/frontend/components/sidebar.d.ts"
@@ -117,6 +198,34 @@
       "import": "./dist/frontend/components/settings.js",
       "types": "./dist/frontend/components/settings.d.ts"
     },
+    "./frontend/types": {
+      "import": "./dist/frontend/types.js",
+      "types": "./dist/frontend/types.d.ts"
+    },
+    "./frontend/keyboard": {
+      "import": "./dist/frontend/keyboard.js",
+      "types": "./dist/frontend/keyboard.d.ts"
+    },
+    "./frontend/folder-refresh": {
+      "import": "./dist/frontend/folder-refresh.js",
+      "types": "./dist/frontend/folder-refresh.d.ts"
+    },
+    "./frontend/utils": {
+      "import": "./dist/frontend/utils.js",
+      "types": "./dist/frontend/utils.d.ts"
+    },
+    "./frontend/utils/clipboard": {
+      "import": "./dist/frontend/utils/clipboard.js",
+      "types": "./dist/frontend/utils/clipboard.d.ts"
+    },
+    "./frontend/utils/dndzone": {
+      "import": "./dist/frontend/utils/dndzone.js",
+      "types": "./dist/frontend/utils/dndzone.d.ts"
+    },
+    "./frontend/api/share": {
+      "import": "./dist/frontend/api/share.js",
+      "types": "./dist/frontend/api/share.d.ts"
+    },
     "./frontend/theme": {
       "import": "./dist/frontend/theme.js",
       "types": "./dist/frontend/theme.d.ts"
@@ -166,12 +275,10 @@
     "packages/db/src/client.ts",
     "packages/db/src/schema.ts",
     "packages/db/src/with-tenant.ts",
-    "packages/cli/src/index.ts",
     "packages/cli/src/client.ts",
     "packages/cli/src/config.ts",
     "packages/cli/src/format.ts",
     "packages/cli/src/commands",
-    "packages/mcp-server/src/index.ts",
     "packages/mcp-server/src/client.ts",
     "packages/mcp-server/src/types.ts",
     "packages/mcp-server/src/tools",

package/packages/cli/src/index.ts

@@ -24,7 +24,7 @@ import { registerSearch } from "./commands/search.js";
 import { registerSnapshot } from "./commands/snapshot.js";
 import { registerUpdate } from "./commands/update.js";
 
-const VERSION = "0.3.5";
+const VERSION = "0.3.7";
 
 const program = new Command();
 program

package/packages/db/src/index.ts

@@ -1,5 +1,14 @@
 export * from "./schema";
 export { db, client } from "./client";
 export type { Database } from "./client";
-export { withTenant, adminTenantContext, shareGuestTenantContext } from "./with-tenant";
-export type { TenantContext } from "./with-tenant";
+export {
+	withTenant,
+	adminTenantContext,
+	shareGuestTenantContext,
+	createActorScopedTransactionExecutor,
+} from "./with-tenant";
+export type {
+	ActorScopedTransactionExecutor,
+	TenantContext,
+	TenantTransaction,
+} from "./with-tenant";

package/packages/db/src/schema.ts

@@ -698,7 +698,8 @@ export const lifecycleOperations = pgTable(
   "lifecycle_operations",
   {
     id: uuid("id").primaryKey().defaultRandom(),
-    actorUserId: uuid("actor_user_id").notNull().references(() => users.id, { onDelete: "restrict" }),
+	actorUserId: uuid("actor_user_id").references(() => users.id, { onDelete: "set null" }),
+	actorSubjectHash: text("actor_subject_hash").notNull(),
     idempotencyKey: text("idempotency_key").notNull(),
     operationKind: lifecycleOperationKindEnum("operation_kind").notNull(),
     status: lifecycleOperationStatusEnum("status").notNull().default("pending"),
@@ -717,7 +718,34 @@ export const lifecycleOperations = pgTable(
     uniqueIndex("lifecycle_operations_actor_idempotency_idx").on(table.actorUserId, table.idempotencyKey),
     index("lifecycle_operations_status_lease_idx").on(table.status, table.leaseExpiresAt),
     index("lifecycle_operations_actor_idx").on(table.actorUserId),
-    index("lifecycle_operations_retryable_idx").on(table.status).where(sql`${table.status} = 'retryable'`),
+	index("lifecycle_operations_retryable_idx").on(table.status).where(sql`${table.status} = 'retryable'`),
+	check("lifecycle_operations_actor_subject_hash", sql`${table.actorSubjectHash} ~ '^[a-f0-9]{64}$'`),
+  ],
+);
+
+// Atomically committed alongside a document and its initial version when an
+// authenticated client supplies Idempotency-Key on POST /api/documents.
+export const documentCreateOperations = pgTable(
+  "document_create_operations",
+  {
+    id: uuid("id").primaryKey().defaultRandom(),
+    workspaceId: text("workspace_id").notNull(),
+    actorUserId: uuid("actor_user_id")
+      .notNull()
+      .references(() => users.id, { onDelete: "cascade" }),
+    idempotencyKey: text("idempotency_key").notNull(),
+    documentId: uuid("document_id")
+      .notNull()
+      .references(() => documents.id, { onDelete: "cascade" }),
+    createdAt: timestamp("created_at").defaultNow().notNull(),
+  },
+  (table) => [
+    uniqueIndex("document_create_operations_workspace_actor_key_idx").on(
+      table.workspaceId,
+      table.actorUserId,
+      table.idempotencyKey,
+    ),
+    uniqueIndex("document_create_operations_document_idx").on(table.documentId),
   ],
 );
 

package/packages/db/src/with-tenant.ts

@@ -1,5 +1,42 @@
 import { sql } from "drizzle-orm";
-import { db } from "./client";
+import { db, type Database } from "./client";
+
+/** A transaction carrying the same query surface as the tenant-scoped DB. */
+export type TenantTransaction = Parameters<
+	Parameters<typeof db.transaction>[0]
+>[0];
+
+/**
+ * Server-side adapter for packages that must run short actor-scoped database
+ * transactions without importing this module's process-global client.
+ */
+export interface ActorScopedTransactionExecutor {
+	withActorTransaction<T>(
+		actorUserId: string,
+		operation: (tx: TenantTransaction) => Promise<T>,
+	): Promise<T>;
+}
+
+export function createActorScopedTransactionExecutor(
+	database: Database,
+): ActorScopedTransactionExecutor {
+	return {
+		withActorTransaction(actorUserId, operation) {
+			return database.transaction(async (tx) => {
+				await tx.execute(
+					sql`SELECT set_config('app.current_user_id', ${actorUserId}, true)`,
+				);
+				await tx.execute(
+					sql`SELECT set_config('app.current_user_role', 'user', true)`,
+				);
+				await tx.execute(
+					sql`SELECT set_config('app.current_workspace_id', '', true)`,
+				);
+				return operation(tx);
+			});
+		},
+	};
+}
 
 export interface TenantContext {
 	userId: string;

package/packages/mcp-server/src/index.ts

@@ -35,7 +35,7 @@ interface McpToolResult {
 
 const server = new McpServer({
 	name: "hiai-docs",
-	version: "0.3.5",
+	version: "0.3.7",
 });
 
 /**