@hiai-gg/docsmint 0.3.4 → 0.3.6

package/dist/storage-quota.js

@@ -0,0 +1,104 @@
+/** 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;
+    limitBytes;
+    requestedBytes;
+    constructor(rejection) {
+        super("Storage quota exceeded");
+        this.name = "StorageQuotaExceededError";
+        this.usageBytes = rejection.usageBytes;
+        this.limitBytes = rejection.limitBytes;
+        this.requestedBytes = rejection.requestedBytes;
+    }
+}
+function assertContext(context) {
+    for (const [name, value] of [
+        ["actorUserId", context.actorUserId],
+        ["requestId", context.requestId],
+        ["idempotencyKey", context.idempotencyKey],
+    ]) {
+        if (!value.trim())
+            throw new TypeError(`${name} must not be empty`);
+    }
+    if (context.signal?.aborted) {
+        throw new DOMException("Storage quota operation aborted", "AbortError");
+    }
+}
+function assertPositiveBytes(bytes, name) {
+    if (!Number.isSafeInteger(bytes) || bytes <= 0) {
+        throw new TypeError(`${name} must be a positive safe integer`);
+    }
+}
+function assertNonnegativeBytes(bytes, name) {
+    if (!Number.isSafeInteger(bytes) || bytes < 0) {
+        throw new TypeError(`${name} must be a non-negative safe integer`);
+    }
+}
+function assertReservation(result) {
+    assertReservationId(result.reservationId);
+    assertPositiveBytes(result.reservedBytes, "reservedBytes");
+    assertNonnegativeBytes(result.usageBytes, "usageBytes");
+    assertNonnegativeBytes(result.limitBytes, "limitBytes");
+    if (Number.isNaN(Date.parse(result.expiresAt))) {
+        throw new TypeError("expiresAt must be an ISO-compatible timestamp");
+    }
+}
+function assertRejection(result) {
+    assertNonnegativeBytes(result.usageBytes, "usageBytes");
+    assertNonnegativeBytes(result.limitBytes, "limitBytes");
+    assertPositiveBytes(result.requestedBytes, "requestedBytes");
+}
+function assertReservationId(value) {
+    if (!value.trim())
+        throw new TypeError("reservationId must not be empty");
+}
+export function createStorageQuotaService(adapter) {
+    return Object.freeze({
+        async reserve(request) {
+            assertContext(request);
+            assertPositiveBytes(request.bytes, "bytes");
+            const result = await adapter.reserve(Object.freeze({ ...request }));
+            if (result.status === "rejected") {
+                assertRejection(result);
+                throw new StorageQuotaExceededError(result);
+            }
+            assertReservation(result);
+            return Object.freeze({ ...result });
+        },
+        async commit(request) {
+            assertContext(request);
+            assertReservationId(request.reservationId);
+            assertPositiveBytes(request.actualBytes, "actualBytes");
+            const result = await adapter.commit(Object.freeze({ ...request }));
+            if (result.status !== "committed" &&
+                result.status !== "already_committed") {
+                throw new TypeError("Storage quota adapter returned an invalid commit status");
+            }
+            return Object.freeze({ ...result });
+        },
+        async release(request) {
+            assertContext(request);
+            assertReservationId(request.reservationId);
+            const result = await adapter.release(Object.freeze({ ...request }));
+            if (result.status !== "released" &&
+                result.status !== "already_released" &&
+                result.status !== "not_found") {
+                throw new TypeError("Storage quota adapter returned an invalid release 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,9 +1,12 @@
 {
   "name": "@hiai-gg/docsmint",
-  "version": "0.3.4",
+  "version": "0.3.6",
   "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
   },
   "license": "Apache-2.0",
@@ -61,6 +64,16 @@
       "import": "./dist/workspace.js",
       "types": "./dist/workspace.d.ts"
     },
+    "./backend/launcher": {
+      "browser": "./dist/server-only-browser-entry.js",
+      "import": "./dist/backend-launcher.js",
+      "types": "./dist/backend-launcher.d.ts"
+    },
+    "./storage-quota": {
+      "browser": "./dist/server-only-browser-entry.js",
+      "import": "./dist/storage-quota.js",
+      "types": "./dist/storage-quota.d.ts"
+    },
     "./frontend/dashboard": {
       "import": "./dist/frontend/dashboard.js",
       "types": "./dist/frontend/dashboard.d.ts"
@@ -154,12 +167,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.4";
+const VERSION = "0.3.6";
 
 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.4",
+	version: "0.3.6",
 });
 
 /**