studiograph 1.3.48-next.2 → 1.3.48-next.201

package/dist/services/asset-finalize-service.d.ts

@@ -0,0 +1,58 @@
+/**
+ * MCP pre-signed asset upload — STEP 3 of 3.
+ *
+ * The agent has PUT bytes to the pre-signed URL minted by presign; this
+ * verifies the upload landed, validates content-type + size at the wire,
+ * promotes the blob from `pending/` to canonical keyspace, creates the
+ * asset entity, and writes the ownership index row.
+ *
+ * Layered guarantees (every one mapped to a plan decision):
+ *  - Tamper-proof (T2):    verifyAssetUploadToken throws TokenInvalidError on
+ *                           tamper / wrong-secret / expiry.
+ *  - Identity-pin (R1):    String(user.id) === payload.uploaderUserId.
+ *                           Leaked token cannot be replayed by another
+ *                           folder-writer (and workspace owner is NOT exempt).
+ *  - Idempotent (plan):    assetIndex.get(assetId) → existing row's URL.
+ *                           Safe retries on transient network errors at the
+ *                           agent's end.
+ *  - Authz freshness:      Re-check canWriteRepo. 15-min token outlives a
+ *                           folder-access revoke.
+ *  - Wire-level validation: HEAD pending and assert stored Content-Type
+ *                           matches the token's `mime`, and Content-Length
+ *                           ≤ 20MB. On mismatch, delete pending immediately
+ *                           so the user doesn't get charged for it.
+ *  - Atomic-ish promote:   r2.copy (pending → canonical) is server-side.
+ *  - Compensating delete (R5): if entity-create OR index.put throws AFTER
+ *                           the canonical copy succeeded, delete the
+ *                           canonical blob so we don't leave a body-less
+ *                           asset entity OR an entity-less blob. If THAT
+ *                           also fails, log CRITICAL with the orphaned key.
+ *  - Audit log (R3):       single structured line at every outcome (success
+ *                           and each reject reason). Forensics + post-
+ *                           incident reconstruction.
+ *
+ * See ~/.claude/plans/mcp-presigned-asset-upload.md.
+ */
+import type { WorkspaceManager } from '../core/workspace-manager.js';
+import type { AuthService, AuthUser } from './auth-service.js';
+export interface FinalizeAssetInput {
+    workspaceManager: WorkspaceManager;
+    authService: AuthService;
+    user: AuthUser;
+    /** HMAC token minted by `presignAssetUpload`. */
+    token: string;
+    /** Optional display name for the asset entity. Defaults to a title-cased
+     *  version of the filename stem. */
+    name?: string;
+}
+export interface FinalizeAssetOutput {
+    assetId: string;
+    /** `/api/assets/{assetId}/{filename}` — the proxied URL that resolves
+     *  per-request to a short-lived signed R2 URL via the asset-api route. */
+    url: string;
+    ownerType: string;
+    ownerId: string;
+    /** Resolved repo (echoed from the token for the MCP tool to surface). */
+    repo: string;
+}
+export declare function finalizeAssetUpload(input: FinalizeAssetInput): Promise<FinalizeAssetOutput>;

package/dist/services/asset-finalize-service.js

@@ -0,0 +1,207 @@
+/**
+ * MCP pre-signed asset upload — STEP 3 of 3.
+ *
+ * The agent has PUT bytes to the pre-signed URL minted by presign; this
+ * verifies the upload landed, validates content-type + size at the wire,
+ * promotes the blob from `pending/` to canonical keyspace, creates the
+ * asset entity, and writes the ownership index row.
+ *
+ * Layered guarantees (every one mapped to a plan decision):
+ *  - Tamper-proof (T2):    verifyAssetUploadToken throws TokenInvalidError on
+ *                           tamper / wrong-secret / expiry.
+ *  - Identity-pin (R1):    String(user.id) === payload.uploaderUserId.
+ *                           Leaked token cannot be replayed by another
+ *                           folder-writer (and workspace owner is NOT exempt).
+ *  - Idempotent (plan):    assetIndex.get(assetId) → existing row's URL.
+ *                           Safe retries on transient network errors at the
+ *                           agent's end.
+ *  - Authz freshness:      Re-check canWriteRepo. 15-min token outlives a
+ *                           folder-access revoke.
+ *  - Wire-level validation: HEAD pending and assert stored Content-Type
+ *                           matches the token's `mime`, and Content-Length
+ *                           ≤ 20MB. On mismatch, delete pending immediately
+ *                           so the user doesn't get charged for it.
+ *  - Atomic-ish promote:   r2.copy (pending → canonical) is server-side.
+ *  - Compensating delete (R5): if entity-create OR index.put throws AFTER
+ *                           the canonical copy succeeded, delete the
+ *                           canonical blob so we don't leave a body-less
+ *                           asset entity OR an entity-less blob. If THAT
+ *                           also fails, log CRITICAL with the orphaned key.
+ *  - Audit log (R3):       single structured line at every outcome (success
+ *                           and each reject reason). Forensics + post-
+ *                           incident reconstruction.
+ *
+ * See ~/.claude/plans/mcp-presigned-asset-upload.md.
+ */
+import { canWriteRepo } from './access-control.js';
+import { verifyAssetUploadToken } from './asset-upload-token.js';
+import { publicUrlForAssetId } from './assets/index.js';
+import { ForbiddenError, LocalBackendNotSupportedError, UploadNotReceivedError, UploadValidationError, } from './asset-upload-errors.js';
+import { log } from '../utils/log.js';
+const MAX_BYTES = 20 * 1024 * 1024;
+export async function finalizeAssetUpload(input) {
+    // 1. Token verify (throws TokenInvalidError on any failure).
+    const payload = verifyAssetUploadToken(input.token, input.authService.getJwtSecret());
+    // Common audit-log scaffold so every outcome carries the same fields.
+    const auditBase = {
+        event: 'asset-finalize',
+        userId: String(input.user.id),
+        repo: payload.repo,
+        ownerType: payload.ownerType,
+        ownerId: payload.ownerId,
+        assetId: payload.assetId,
+    };
+    const reject = (reason, error) => {
+        log.info('[asset-finalize]', { ...auditBase, outcome: 'rejected', reason });
+        throw error;
+    };
+    // 2. R1 identity bind: token leak isn't replayable by another user.
+    //    Workspace owner is NOT exempt — the uploaderUserId rule applies to
+    //    everyone, mirroring the canDelete rule on the workspace assets store.
+    if (String(input.user.id) !== payload.uploaderUserId) {
+        reject('identity_mismatch', new ForbiddenError('finalize_asset_upload may only be called by the user who created the upload token'));
+    }
+    const assetIndex = input.workspaceManager.getAssetIndex();
+    // 3. Idempotency. A repeat finalize with the same token returns the
+    //    existing asset row — covers agent retries on network hiccup between
+    //    "201 from R2" and "response from finalize".
+    const existing = assetIndex.get(payload.assetId);
+    if (existing) {
+        log.info('[asset-finalize]', { ...auditBase, outcome: 'idempotent' });
+        return {
+            assetId: existing.assetId,
+            url: publicUrlForAssetId(existing.assetId, existing.filename),
+            ownerType: existing.ownerType,
+            ownerId: existing.ownerId,
+            repo: existing.repo,
+        };
+    }
+    // 4. Re-check folder authz. 15-min token may outlive a folder-access
+    //    revoke; closes the "demoted-mid-flow" gap.
+    if (!canWriteRepo(input.user, payload.repo, input.workspaceManager, input.authService)) {
+        reject('forbidden_repo', new ForbiddenError(`No write access to folder "${payload.repo}"`));
+    }
+    // 5. Resolve the graph + asset service for the target repo.
+    let graph;
+    try {
+        graph = input.workspaceManager.getGraph(payload.repo);
+    }
+    catch {
+        reject('repo_not_found', new ForbiddenError(`Folder "${payload.repo}" not found`));
+    }
+    const assetService = graph.getAssetService();
+    if (!assetService || !assetService.supportsPresignedUploads()) {
+        reject('local_backend', new LocalBackendNotSupportedError('Pre-signed uploads require an R2-backed asset store'));
+    }
+    // 6. HEAD pending — covers "agent never PUT", wrong CT, oversize. On
+    //    mismatch, delete pending immediately so a misbehaving agent's bytes
+    //    don't sit on the lifecycle clock at our cost.
+    const head = await assetService.headPending(payload.assetId, payload.filename);
+    if (!head) {
+        log.info('[asset-finalize]', { ...auditBase, outcome: 'rejected', reason: 'upload_not_received' });
+        throw new UploadNotReceivedError(`No upload received at pending/${payload.assetId}/${payload.filename}. PUT may have failed or the 15-min window expired.`);
+    }
+    if (head.contentType !== payload.mime) {
+        await safeDeletePending(assetService, payload.assetId, payload.filename);
+        log.info('[asset-finalize]', {
+            ...auditBase, outcome: 'rejected', reason: 'content_type_mismatch',
+            expected: payload.mime, actual: head.contentType,
+        });
+        throw new UploadValidationError(`Stored Content-Type "${head.contentType}" does not match presign mime "${payload.mime}".`);
+    }
+    if (head.size > MAX_BYTES) {
+        await safeDeletePending(assetService, payload.assetId, payload.filename);
+        log.info('[asset-finalize]', {
+            ...auditBase, outcome: 'rejected', reason: 'oversize', size: head.size, max: MAX_BYTES,
+        });
+        throw new UploadValidationError(`Upload size ${head.size} bytes exceeds ${MAX_BYTES} byte limit.`);
+    }
+    if (head.size === 0) {
+        await safeDeletePending(assetService, payload.assetId, payload.filename);
+        log.info('[asset-finalize]', { ...auditBase, outcome: 'rejected', reason: 'empty' });
+        throw new UploadValidationError('Upload is empty (0 bytes).');
+    }
+    // 7. Server-side promote pending → canonical. CopyObject is atomic at
+    //    R2; on failure, leave pending for the lifecycle rule.
+    await assetService.copyPendingToCanonical(payload.assetId, payload.filename);
+    // 8. From here on, the canonical blob EXISTS. Any failure below must
+    //    delete it (R5) so we don't leave an orphan with no entity owner.
+    const url = publicUrlForAssetId(payload.assetId, payload.filename);
+    const stem = payload.filename.replace(/\.[^.]+$/, '');
+    const fallbackName = stem.replace(/[_-]+/g, ' ').replace(/\b\w/g, c => c.toUpperCase());
+    const name = input.name?.trim() || fallbackName || payload.assetId;
+    // Asset-as-embed (B2): presign produces a FREE-STANDING, folder-owned asset —
+    // NO `asset` entity. The agent embeds it into an entry via
+    // attach_asset_to_entity, or a user re-embeds it via the manager / "create
+    // entry from asset". The folder-owned index row is the asset's record of
+    // existence. NOTE: image caption/OCR indexing is NOT derived for a
+    // free-standing asset — the caption sweep + live drain are keyed to `asset`
+    // ENTITIES (vector-service / asset-index-sweep), which this path no longer
+    // creates, so these assets stay filename/body-only in vector search until the
+    // caption pipeline is rewired to be assets.db-row-keyed (tracked follow-up).
+    try {
+        assetIndex.put({
+            assetId: payload.assetId,
+            repo: payload.repo,
+            ownerType: 'folder',
+            ownerId: payload.repo,
+            filename: payload.filename,
+            contentType: payload.mime,
+            mediaType: 'image',
+            name,
+            uploaderUserId: String(input.user.id),
+            size: head.size,
+        });
+    }
+    catch (err) {
+        // R5: index.put failed after the canonical blob was copied — delete the
+        // blob so no orphan remains; the original error propagates. (No entity to
+        // roll back under the asset-as-embed model.)
+        try {
+            await assetService.deleteByAssetId(payload.assetId, payload.filename);
+        }
+        catch (cleanupErr) {
+            log.warn('[asset-finalize] CRITICAL: compensating delete failed, canonical blob orphaned', {
+                assetId: payload.assetId,
+                canonicalKey: `${payload.assetId}/${payload.filename}`,
+                cleanupErr: cleanupErr instanceof Error ? cleanupErr.message : String(cleanupErr),
+            });
+        }
+        log.info('[asset-finalize]', { ...auditBase, outcome: 'rejected', reason: 'app_layer_failure' });
+        throw err;
+    }
+    // 9. Pending cleanup — non-fatal. Canonical exists; lifecycle catches
+    //    a missed delete.
+    try {
+        await assetService.deletePending(payload.assetId, payload.filename);
+    }
+    catch (err) {
+        log.warn('[asset-finalize] pending delete failed (canonical exists; lifecycle backstop will reap)', {
+            assetId: payload.assetId,
+            err: err instanceof Error ? err.message : String(err),
+        });
+    }
+    // 10. Success audit log.
+    log.info('[asset-finalize]', { ...auditBase, outcome: 'success', size: head.size, mime: payload.mime });
+    return {
+        assetId: payload.assetId,
+        url,
+        ownerType: 'folder',
+        ownerId: payload.repo,
+        repo: payload.repo,
+    };
+}
+/** Best-effort pending delete on validation rejects. Errors here are
+ *  swallowed — the lifecycle rule is the backstop and we don't want a
+ *  cleanup failure to mask the user-facing validation error. */
+async function safeDeletePending(assetService, assetId, filename) {
+    try {
+        await assetService.deletePending(assetId, filename);
+    }
+    catch (err) {
+        log.warn('[asset-finalize] best-effort pending delete failed', {
+            assetId, filename, err: err instanceof Error ? err.message : String(err),
+        });
+    }
+}
+//# sourceMappingURL=asset-finalize-service.js.map

package/dist/services/asset-finalize-service.js.map

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

package/dist/services/asset-import-service.d.ts

@@ -0,0 +1,111 @@
+/**
+ * Asset Import Service — the asset-as-embed core (Phase B).
+ *
+ * Replaced the old "upload as a self-owning `asset` entity, convert later"
+ * flow (the `uploadAsset` primitive + a `convertAsset` orchestrator, both
+ * removed in Phase B2/E). An import now:
+ *
+ *   1. Stores the binary as a FREE-STANDING asset owned by the FOLDER (the
+ *      repo), via graph.uploadAsset's `owner` override (Phase A). The blob +
+ *      assets.db row belong to the folder, never to any entity — so deleting
+ *      the entity that embeds it leaves the asset intact + re-embeddable.
+ *   2. Seeds a properly-TYPED graph entity whose BODY embeds the asset, exactly
+ *      as a user would type it — the reference lives in the markdown, not the
+ *      frontmatter:
+ *        image                 → `material`, body `![name](url)` (inline embed)
+ *        opaque binary         → `material`, body `[name](url)` (download link)
+ *        docx / pdf            → `document`, body = a `[name](url)` source link
+ *                                (extraction is lossy) + an "Extracted text"
+ *                                heading + the extracted text
+ *        xlsx                  → `dataset` × N (pure-CSV body; the CSV is a
+ *                                faithful translation so no body reference —
+ *                                the source xlsx is invisible `asset_ref`
+ *                                provenance in frontmatter, the lone exception)
+ *
+ * Decisions (see ~/.claude/plans/asset-as-embed.md; body-embed model 2026-06-01):
+ *   - NO asset-text sidecar is written. Extraction runs in-memory ONLY to seed
+ *     the body, which the vector indexer indexes natively.
+ *   - Body embeds point at the FREE-STANDING, folder-owned asset (Phase A/B
+ *     storage is unchanged → still delete-safe, re-embeddable, many-to-many).
+ *     A broken/missing embed renders as a compact inline note via the editor's
+ *     image-render layer (live-preview.ts), NOT detail-page chrome.
+ *   - On entity-create failure AFTER the blob is stored, roll back with the same
+ *     3-step compensating delete asset-finalize-service uses: delete any created
+ *     entity (keepAssets) → delete the blob → delete the index row. (Relaxes to
+ *     "leave the folder-owned asset" once Phase D surfaces ownerless assets.)
+ *   - xlsx with more than XLSX_SHEET_CAP sheets does NOT fan out — it falls back
+ *     to a single `material` (the binary is preserved; no unbounded entity churn).
+ *
+ *   IMPORT(file, folder)
+ *     ├─ store bytes  → {assetId}/{filename}   owner = { folder, repo }
+ *     ├─ seed body (in-memory; NO sidecar) — embed/link in the markdown
+ *     └─ create typed entity(ies)
+ *          image/opaque → material · docx/pdf → document · xlsx → dataset×N
+ *   FAIL after store  → delete created entities (keepAssets) → delete blob → delete index row
+ */
+import type { BaseGraphManager } from '../core/graph.js';
+import type { EntityType } from '../core/validation.js';
+import type { GitUser } from './git.js';
+export interface ImportAssetAsEntityOptions {
+    graph: BaseGraphManager;
+    /** Original filename from the client. Only the basename is used. */
+    filename: string;
+    buffer: Buffer;
+    /** Repo-relative subfolder for the new entity's .md file(s). */
+    folderPath?: string;
+    /** Override entity name; defaults to the title-cased filename stem. */
+    name?: string;
+    user?: GitUser;
+    /** Defer the git commit so the caller can batch (multi-file import). */
+    skipCommit?: boolean;
+    /** Auth user id of the uploader (web). Recorded in assets.db for the
+     *  uploader+owner delete rule. Null for CLI/import/agent. */
+    uploaderUserId?: string | null;
+}
+/** One typed entity created by the import (1 for doc/material, N for xlsx). */
+export interface ImportedEntity {
+    entityId: string;
+    entityType: EntityType;
+    /** Absolute path of the created `.md` file (for the batched commit). */
+    filePath: string;
+}
+export interface ImportAssetAsEntityResult {
+    /** The free-standing asset's immutable storage UUID. */
+    assetId: string;
+    /** Canonical serving URL for the stored asset. */
+    asset_url: string;
+    /** Every typed entity created (body embeds the asset; only `dataset` carries
+     *  `asset_ref` frontmatter — see seedUnits). */
+    entities: ImportedEntity[];
+}
+/**
+ * Import a binary as a typed graph entity that embeds a free-standing,
+ * folder-owned asset. Returns the assetId + every created entity. Throws on
+ * unsupported extension / empty buffer / unconfigured asset storage, and on
+ * entity-create failure (after rolling back the stored blob + index row).
+ */
+export declare function importAssetAsEntity(opts: ImportAssetAsEntityOptions): Promise<ImportAssetAsEntityResult>;
+export interface CreateEntityFromAssetOptions {
+    graph: BaseGraphManager;
+    /** Immutable id of an EXISTING free-standing asset (assets.db row + blob). */
+    assetId: string;
+    /** Override entity name; defaults to the asset's stored name / filename stem. */
+    name?: string;
+    /** Repo-relative subfolder; defaults to the asset's own folder (repo root). */
+    folderPath?: string;
+    user?: GitUser;
+    skipCommit?: boolean;
+}
+/**
+ * The second import "door": create a properly-TYPED entity that embeds an asset
+ * ALREADY in the store — by its assetId — instead of fresh bytes. This is what
+ * makes deletion reversible: delete an entry, the free-standing asset survives
+ * in the manager, and this re-embeds it into a new entry. Same body-seeding as
+ * the import door (auto-derived type, re-extracted text for docs/sheets), but
+ * NO upload and NO asset-rollback — the asset pre-exists and may be embedded
+ * elsewhere, so a create failure only rolls back the new entities.
+ *
+ * Throws if the asset doesn't exist, storage isn't configured, or the stored
+ * bytes can't be read back for extraction.
+ */
+export declare function createEntityFromAsset(opts: CreateEntityFromAssetOptions): Promise<ImportAssetAsEntityResult>;