studiograph 1.3.48-next.21 → 1.3.48-next.211

package/dist/services/asset-upload-errors.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Typed Error classes for the MCP pre-signed asset upload flow.
+ *
+ * The presign and finalize services throw these; `errorToMcpResult()` in
+ * `mcp/tools.ts` maps each to a `fail()` envelope with a `code` discriminator
+ * the agent can branch on. Generic `Error` thrown from the same call sites
+ * fall through to the default "unknown" code. See ~/.claude/plans/
+ * mcp-presigned-asset-upload.md decision R4.
+ *
+ * The `code` field is read by clients; the message is human-facing. Keep
+ * codes stable across releases — agent prompts and downstream MCP-host UIs
+ * key off them.
+ */
+export declare class AssetUploadError extends Error {
+    /** Stable machine-readable identifier. Set by each subclass; the base
+     *  class declares it so a generic catch can read `err.code` without a
+     *  narrowing dance. */
+    readonly code: string;
+    constructor(message: string);
+}
+export declare class InvalidMimeTypeError extends AssetUploadError {
+    readonly code = "invalid_mime";
+}
+export declare class InvalidFilenameError extends AssetUploadError {
+    readonly code = "invalid_filename";
+}
+export declare class ForbiddenError extends AssetUploadError {
+    readonly code = "forbidden";
+}
+export declare class LocalBackendNotSupportedError extends AssetUploadError {
+    readonly code = "local_backend";
+}
+export declare class TokenInvalidError extends AssetUploadError {
+    readonly code = "token_invalid";
+}
+export declare class UploadNotReceivedError extends AssetUploadError {
+    readonly code = "upload_not_received";
+}
+export declare class UploadValidationError extends AssetUploadError {
+    readonly code = "upload_validation";
+}

package/dist/services/asset-upload-errors.js

@@ -0,0 +1,45 @@
+/**
+ * Typed Error classes for the MCP pre-signed asset upload flow.
+ *
+ * The presign and finalize services throw these; `errorToMcpResult()` in
+ * `mcp/tools.ts` maps each to a `fail()` envelope with a `code` discriminator
+ * the agent can branch on. Generic `Error` thrown from the same call sites
+ * fall through to the default "unknown" code. See ~/.claude/plans/
+ * mcp-presigned-asset-upload.md decision R4.
+ *
+ * The `code` field is read by clients; the message is human-facing. Keep
+ * codes stable across releases — agent prompts and downstream MCP-host UIs
+ * key off them.
+ */
+export class AssetUploadError extends Error {
+    /** Stable machine-readable identifier. Set by each subclass; the base
+     *  class declares it so a generic catch can read `err.code` without a
+     *  narrowing dance. */
+    code = 'asset_upload_error';
+    constructor(message) {
+        super(message);
+        this.name = this.constructor.name;
+    }
+}
+export class InvalidMimeTypeError extends AssetUploadError {
+    code = 'invalid_mime';
+}
+export class InvalidFilenameError extends AssetUploadError {
+    code = 'invalid_filename';
+}
+export class ForbiddenError extends AssetUploadError {
+    code = 'forbidden';
+}
+export class LocalBackendNotSupportedError extends AssetUploadError {
+    code = 'local_backend';
+}
+export class TokenInvalidError extends AssetUploadError {
+    code = 'token_invalid';
+}
+export class UploadNotReceivedError extends AssetUploadError {
+    code = 'upload_not_received';
+}
+export class UploadValidationError extends AssetUploadError {
+    code = 'upload_validation';
+}
+//# sourceMappingURL=asset-upload-errors.js.map

package/dist/services/asset-upload-errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"asset-upload-errors.js","sourceRoot":"","sources":["../../src/services/asset-upload-errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,MAAM,OAAO,gBAAiB,SAAQ,KAAK;IACzC;;2BAEuB;IACd,IAAI,GAAW,oBAAoB,CAAC;IAE7C,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC;IACpC,CAAC;CACF;AAED,MAAM,OAAO,oBAAqB,SAAQ,gBAAgB;IAC/C,IAAI,GAAG,cAAc,CAAC;CAChC;AAED,MAAM,OAAO,oBAAqB,SAAQ,gBAAgB;IAC/C,IAAI,GAAG,kBAAkB,CAAC;CACpC;AAED,MAAM,OAAO,cAAe,SAAQ,gBAAgB;IACzC,IAAI,GAAG,WAAW,CAAC;CAC7B;AAED,MAAM,OAAO,6BAA8B,SAAQ,gBAAgB;IACxD,IAAI,GAAG,eAAe,CAAC;CACjC;AAED,MAAM,OAAO,iBAAkB,SAAQ,gBAAgB;IAC5C,IAAI,GAAG,eAAe,CAAC;CACjC;AAED,MAAM,OAAO,sBAAuB,SAAQ,gBAAgB;IACjD,IAAI,GAAG,qBAAqB,CAAC;CACvC;AAED,MAAM,OAAO,qBAAsB,SAAQ,gBAAgB;IAChD,IAAI,GAAG,mBAAmB,CAAC;CACrC"}

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

@@ -0,0 +1,56 @@
+/**
+ * Asset Upload Service
+ *
+ * Single primitive for "store a binary, create a wrapper entity that
+ * points at it." Used by both the standalone `POST /api/repos/:repo/assets`
+ * route and the multi-file import dispatcher when it sees a binary
+ * extension.
+ *
+ * Flow per file:
+ *   1. Validate extension against `ASSET_UPLOAD_EXTENSIONS`.
+ *   2. Create the `asset` entity with stub frontmatter (collision-retry
+ *      on entity_id, same `foo`→`foo-2` semantics as import-service).
+ *   3. Upload the binary via `graph.uploadAsset` — picks R2 or local
+ *      filesystem from the workspace's asset config.
+ *   4. PDFs: extract text + page count via `pdf-parse`, write the text
+ *      to a sidecar at `<workspace>/.studiograph/assets-text/asset/{id}.txt`
+ *      so the vector indexer can RAG it without bloating the markdown body.
+ *   5. Update the entity with the resolved `asset_url` and per-kind
+ *      metadata (`pages`, future `width`/`height`).
+ */
+import type { BaseGraphManager } from '../core/graph.js';
+import type { AssetKind } from '../core/validation.js';
+import type { GitUser } from './git.js';
+export interface UploadAssetOptions {
+    graph: BaseGraphManager;
+    /** Original filename from the client. May contain path segments — only the basename is used. */
+    filename: string;
+    buffer: Buffer;
+    /** Repo-relative folder for the new entity's .md file. Empty/undefined = repo root. */
+    folderPath?: string;
+    /** Override entity name; defaults to title-cased slug of the filename stem. */
+    name?: string;
+    user?: GitUser;
+    /** Defer git commit so the caller can batch (e.g. multi-file imports). Default false. */
+    skipCommit?: boolean;
+    /** Workspace root used to anchor the PDF text sidecar at
+     *  `<workspacePath>/.studiograph/assets-text/asset/{id}.txt`. When
+     *  undefined, sidecars are not written (the asset still uploads). */
+    workspacePath?: string;
+    /** Auth user id of the uploader (web). Recorded in the asset index for the
+     *  uploader+owner delete rule. Omit for CLI/import — stored as null. */
+    uploaderUserId?: string | null;
+}
+export interface UploadAssetResult {
+    entityId: string;
+    entityType: 'asset';
+    /** Absolute path of the created `.md` entity file. */
+    filePath: string;
+    asset_url: string;
+    asset_kind: AssetKind;
+    asset_size: number;
+    pages?: number;
+    /** Sidecar path when one was written (PDF only). Caller can include in batched commit's extraPaths. */
+    sidecarPath?: string;
+}
+export declare function uploadAsset(opts: UploadAssetOptions): Promise<UploadAssetResult>;

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

@@ -0,0 +1,200 @@
+/**
+ * Asset Upload Service
+ *
+ * Single primitive for "store a binary, create a wrapper entity that
+ * points at it." Used by both the standalone `POST /api/repos/:repo/assets`
+ * route and the multi-file import dispatcher when it sees a binary
+ * extension.
+ *
+ * Flow per file:
+ *   1. Validate extension against `ASSET_UPLOAD_EXTENSIONS`.
+ *   2. Create the `asset` entity with stub frontmatter (collision-retry
+ *      on entity_id, same `foo`→`foo-2` semantics as import-service).
+ *   3. Upload the binary via `graph.uploadAsset` — picks R2 or local
+ *      filesystem from the workspace's asset config.
+ *   4. PDFs: extract text + page count via `pdf-parse`, write the text
+ *      to a sidecar at `<workspace>/.studiograph/assets-text/asset/{id}.txt`
+ *      so the vector indexer can RAG it without bloating the markdown body.
+ *   5. Update the entity with the resolved `asset_url` and per-kind
+ *      metadata (`pages`, future `width`/`height`).
+ */
+import { extname, basename, join } from 'path';
+import { existsSync, mkdirSync, writeFileSync } from 'fs';
+import { log } from '../utils/log.js';
+import { detectAssetKind, detectContentType, isAssetUploadExtension, safeFilename, } from './assets/base.js';
+const slugify = (str) => str.toLowerCase().trim().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '');
+const formatName = (slug) => slug.replace(/-/g, ' ').replace(/\b\w/g, c => c.toUpperCase());
+export async function uploadAsset(opts) {
+    const { graph, buffer, folderPath, user, skipCommit = false, workspacePath } = opts;
+    const onlyName = basename(opts.filename);
+    const ext = extname(onlyName).toLowerCase();
+    if (!isAssetUploadExtension(onlyName)) {
+        throw new Error(`Unsupported asset extension: ${ext || '(none)'}`);
+    }
+    if (!buffer || buffer.length === 0) {
+        throw new Error('Asset upload received an empty buffer');
+    }
+    const assetKind = detectAssetKind(onlyName);
+    const mime = detectContentType(onlyName);
+    // Probe asset configuration before mutating the graph. listAssets() is
+    // cheap and surfaces a helpful error when R2/local storage isn't
+    // wired up — better to fail before creating a stub entity that has
+    // nowhere to point at.
+    try {
+        await graph.listAssets('asset', '__check__');
+    }
+    catch (err) {
+        if (err.message?.includes('not configured')) {
+            throw new Error('Asset storage is not configured for this workspace.');
+        }
+        // Other errors (e.g. entity-not-found) just mean the service IS configured.
+    }
+    const stem = onlyName.replace(/\.[^.]+$/, '');
+    const baseId = (slugify(stem).slice(0, 80).replace(/-$/, '')) || `asset-${Date.now()}`;
+    const name = opts.name ?? formatName(baseId);
+    const now = new Date().toISOString();
+    const userHandle = user?.email?.split('@')[0] ?? user?.name ?? 'upload';
+    const stubData = {
+        entity_type: 'asset',
+        entity_id: baseId,
+        name,
+        // Stub URL — populated post-upload. Required by the schema; '__pending__'
+        // is replaced before the second commit lands.
+        asset_url: '__pending__',
+        asset_kind: assetKind,
+        asset_extension: ext,
+        asset_size: buffer.length,
+        asset_mime: mime,
+        created_at: now,
+        updated_at: now,
+        created_by: userHandle,
+        updated_by: userHandle,
+    };
+    // Collision retry on (asset, entity_id). Mirrors the suffix scheme in
+    // import-service.createWithCollisionRetry — keeps re-uploads from
+    // silently dropping files.
+    let entityId = baseId;
+    let createdPath;
+    let suffix = 0;
+    while (true) {
+        entityId = suffix === 0 ? baseId : `${baseId}-${suffix + 1}`;
+        try {
+            const created = await graph.create({
+                entityType: 'asset',
+                entityId,
+                data: { ...stubData, entity_id: entityId },
+                content: '',
+                folderPath,
+                skipCommit: true,
+                user,
+            });
+            createdPath = created.path;
+            break;
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            if (!msg.includes('already exists') || suffix >= 50)
+                throw err;
+            suffix++;
+        }
+    }
+    // Everything past this point operates on a real on-disk stub entity
+    // with `asset_url: '__pending__'`. If any step throws, the stub must be
+    // rolled back — otherwise the entity persists with a placeholder URL
+    // that surfaces as a broken asset in list/gallery/search/RAG. Rollback
+    // commits a delete (graph.delete is auto-commit-only by design); on the
+    // batch import path that's one extra commit per failure, which is
+    // acceptable on a failure path.
+    let pages;
+    let sidecarPath;
+    let asset_url;
+    try {
+        // Storage filename gets a Date.now() prefix to dodge same-name re-uploads.
+        const storedFilename = `${Date.now()}-${safeFilename(onlyName)}`;
+        const asset = await graph.uploadAsset('asset', entityId, storedFilename, buffer, undefined, { uploaderUserId: opts.uploaderUserId ?? null });
+        // PDF metadata extraction. pdf-parse is CPU-bound and runs on the
+        // request thread — gate by size so a 100MB PDF doesn't stall the
+        // event loop for every other in-flight Fastify request. Asset still
+        // uploads; it just won't be RAG-searchable until a future re-extract.
+        if (assetKind === 'pdf') {
+            const PDF_TEXT_BYTES_CAP = 20 * 1024 * 1024;
+            if (buffer.length > PDF_TEXT_BYTES_CAP) {
+                log.warn(`[asset-upload] PDF text extraction skipped for ${entityId}: ${buffer.length} bytes > ${PDF_TEXT_BYTES_CAP} cap`);
+            }
+            else {
+                let extractedText = '';
+                try {
+                    const { PDFParse } = await import('pdf-parse');
+                    const parser = new PDFParse({ data: buffer });
+                    const result = await parser.getText();
+                    await parser.destroy();
+                    if (result.total && result.total > 0)
+                        pages = result.total;
+                    extractedText = result.text?.trim() ?? '';
+                }
+                catch (err) {
+                    // Non-fatal — extraction can fail on encrypted/scanned PDFs.
+                    // Don't conflate with sidecar write failures (infra problem,
+                    // not content problem) — those get their own warn below.
+                    log.warn(`[asset-upload] PDF text extraction failed for ${entityId}: ${err instanceof Error ? err.message : err}`);
+                }
+                if (extractedText && workspacePath) {
+                    try {
+                        const sidecarDir = join(workspacePath, '.studiograph', 'assets-text', 'asset');
+                        if (!existsSync(sidecarDir))
+                            mkdirSync(sidecarDir, { recursive: true });
+                        sidecarPath = join(sidecarDir, `${entityId}.txt`);
+                        writeFileSync(sidecarPath, extractedText, 'utf-8');
+                    }
+                    catch (err) {
+                        // Sidecar write failures (disk full, permissions) leave the
+                        // asset un-RAG-able but otherwise usable. Re-indexing later
+                        // picks it back up if the sidecar appears.
+                        sidecarPath = undefined;
+                        log.warn(`[asset-upload] PDF sidecar write failed for ${entityId}: ${err instanceof Error ? err.message : err}`);
+                    }
+                }
+            }
+        }
+        // Canonical URL from uploadAsset (immutable-key scheme when wired, else
+        // legacy). Don't re-derive — the assetId isn't recoverable from (type,id).
+        asset_url = asset.publicUrl;
+        const updateData = { asset_url };
+        if (pages !== undefined)
+            updateData.pages = pages;
+        await graph.update({
+            entityType: 'asset',
+            entityId,
+            data: updateData,
+            skipCommit: true,
+            user,
+        });
+    }
+    catch (err) {
+        try {
+            await graph.delete('asset', entityId, `Rollback failed asset upload: ${entityId}`, user);
+        }
+        catch (cleanupErr) {
+            log.warn(`[asset-upload] rollback delete failed for ${entityId}: ${cleanupErr instanceof Error ? cleanupErr.message : cleanupErr}`);
+        }
+        throw err;
+    }
+    if (!skipCommit) {
+        const git = graph.getGitService();
+        if (git) {
+            const commitUser = user ?? { id: 'upload', name: 'Upload', email: 'upload@studiograph' };
+            git.commitAll(`Upload asset: ${entityId}`, commitUser);
+        }
+    }
+    return {
+        entityId,
+        entityType: 'asset',
+        filePath: createdPath,
+        asset_url,
+        asset_kind: assetKind,
+        asset_size: buffer.length,
+        pages,
+        sidecarPath,
+    };
+}
+//# sourceMappingURL=asset-upload-service.js.map

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

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

package/dist/services/asset-upload-token.d.ts

@@ -0,0 +1,58 @@
+/**
+ * HMAC-signed token bound to a pending pre-signed asset upload.
+ *
+ * Flow: presign mints a token + signed PUT URL; the agent uploads bytes to
+ * R2 directly, then calls `finalize_asset_upload({ token })`. The token
+ * carries enough state for finalize to find the pending blob, re-check the
+ * caller's authz, and register the asset — without trusting any arg from the
+ * agent. See ~/.claude/plans/mcp-presigned-asset-upload.md.
+ *
+ * Signed with `STUDIOGRAPH_JWT_SECRET` via `authService.getJwtSecret()`.
+ * Reusing the workspace's JWT secret is deliberate: one rotation lever, one
+ * audit boundary, and Phase 4 already env-requires it in production.
+ *
+ * The token is a bearer credential — anything that holds it can finalize as
+ * the original presigner. R1 in the plan closes the leak-and-replay vector
+ * by binding `payload.uploaderUserId` to the calling user at finalize.
+ */
+export interface AssetUploadTokenPayload {
+    /** UUIDv4 generated at presign. Doubles as the entity_id when the asset
+     *  is self-owned (entity == undefined at presign). */
+    assetId: string;
+    /** Resolved repo name. Default = workspace assets folder; otherwise the
+     *  explicit repo the agent passed. Finalize re-checks `canWriteRepo` on
+     *  this. */
+    repo: string;
+    /** Owning entity type. 'asset' when self-owned (no entity attachment),
+     *  else an entity type the agent passed at presign. */
+    ownerType: string;
+    /** Owning entity id. assetId when self-owned, else the entity id. */
+    ownerId: string;
+    /** Auth user id (as string — AuthUser.id is number but the index column
+     *  is TEXT) of the user who presigned. Bound to the finalize caller via
+     *  R1: leaked tokens can't be replayed by another folder-writer. */
+    uploaderUserId: string;
+    /** Pinned mime type. Restricted to the registry's presign-safe set
+     *  (`presignMimeAllowlist()` — png/jpeg/gif/webp/avif/heic; SVG excluded).
+     *  Pinned into the PUT signature so finalize can assert the stored
+     *  Content-Type matches. */
+    mime: string;
+    /** Sanitized filename (post-safeFilename). Used to build the pending key
+     *  and the canonical key — finalize doesn't accept a separate filename
+     *  arg so the agent can't rename mid-flow. */
+    filename: string;
+}
+export declare function signAssetUploadToken(payload: AssetUploadTokenPayload, secret: string): string;
+/**
+ * Verify a token and return the payload. Throws `TokenInvalidError` on:
+ *   - tamper (any field mutated, including assetId)
+ *   - wrong secret (rotation mid-flight)
+ *   - expired (>15min since presign)
+ *   - malformed (not a JWT, wrong shape)
+ *
+ * Caller (finalize) is responsible for the post-verify checks:
+ *   - R1 identity bind: assert `String(user.id) === payload.uploaderUserId`
+ *   - re-check `canWriteRepo(user, payload.repo, ...)`
+ *   - HEAD the pending blob and validate ct + size
+ */
+export declare function verifyAssetUploadToken(token: string, secret: string): AssetUploadTokenPayload;

package/dist/services/asset-upload-token.js

@@ -0,0 +1,75 @@
+/**
+ * HMAC-signed token bound to a pending pre-signed asset upload.
+ *
+ * Flow: presign mints a token + signed PUT URL; the agent uploads bytes to
+ * R2 directly, then calls `finalize_asset_upload({ token })`. The token
+ * carries enough state for finalize to find the pending blob, re-check the
+ * caller's authz, and register the asset — without trusting any arg from the
+ * agent. See ~/.claude/plans/mcp-presigned-asset-upload.md.
+ *
+ * Signed with `STUDIOGRAPH_JWT_SECRET` via `authService.getJwtSecret()`.
+ * Reusing the workspace's JWT secret is deliberate: one rotation lever, one
+ * audit boundary, and Phase 4 already env-requires it in production.
+ *
+ * The token is a bearer credential — anything that holds it can finalize as
+ * the original presigner. R1 in the plan closes the leak-and-replay vector
+ * by binding `payload.uploaderUserId` to the calling user at finalize.
+ */
+import jwt from 'jsonwebtoken';
+import { TokenInvalidError } from './asset-upload-errors.js';
+import { presignMimeAllowlist } from '../core/format-registry.js';
+const TOKEN_TTL_SECONDS = 15 * 60;
+export function signAssetUploadToken(payload, secret) {
+    return jwt.sign(payload, secret, {
+        algorithm: 'HS256',
+        expiresIn: TOKEN_TTL_SECONDS,
+    });
+}
+/**
+ * Verify a token and return the payload. Throws `TokenInvalidError` on:
+ *   - tamper (any field mutated, including assetId)
+ *   - wrong secret (rotation mid-flight)
+ *   - expired (>15min since presign)
+ *   - malformed (not a JWT, wrong shape)
+ *
+ * Caller (finalize) is responsible for the post-verify checks:
+ *   - R1 identity bind: assert `String(user.id) === payload.uploaderUserId`
+ *   - re-check `canWriteRepo(user, payload.repo, ...)`
+ *   - HEAD the pending blob and validate ct + size
+ */
+export function verifyAssetUploadToken(token, secret) {
+    let decoded;
+    try {
+        decoded = jwt.verify(token, secret, { algorithms: ['HS256'] });
+    }
+    catch (err) {
+        throw new TokenInvalidError(err instanceof Error ? err.message : 'token verification failed');
+    }
+    if (!isPayload(decoded)) {
+        throw new TokenInvalidError('token payload has unexpected shape');
+    }
+    return {
+        assetId: decoded.assetId,
+        repo: decoded.repo,
+        ownerType: decoded.ownerType,
+        ownerId: decoded.ownerId,
+        uploaderUserId: decoded.uploaderUserId,
+        mime: decoded.mime,
+        filename: decoded.filename,
+    };
+}
+function isPayload(value) {
+    if (!value || typeof value !== 'object')
+        return false;
+    const v = value;
+    return (typeof v.assetId === 'string' &&
+        typeof v.repo === 'string' &&
+        typeof v.ownerType === 'string' &&
+        typeof v.ownerId === 'string' &&
+        typeof v.uploaderUserId === 'string' &&
+        // Registry-derived presign-safe set (P4-V1). A tampered token carrying a
+        // non-presign-safe mime (svg, pdf, …) still fails validation here.
+        typeof v.mime === 'string' && presignMimeAllowlist().includes(v.mime) &&
+        typeof v.filename === 'string');
+}
+//# sourceMappingURL=asset-upload-token.js.map

package/dist/services/asset-upload-token.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"asset-upload-token.js","sourceRoot":"","sources":["../../src/services/asset-upload-token.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,GAAG,MAAM,cAAc,CAAC;AAC/B,OAAO,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAC7D,OAAO,EAAE,oBAAoB,EAAE,MAAM,4BAA4B,CAAC;AA8BlE,MAAM,iBAAiB,GAAG,EAAE,GAAG,EAAE,CAAC;AAElC,MAAM,UAAU,oBAAoB,CAClC,OAAgC,EAChC,MAAc;IAEd,OAAO,GAAG,CAAC,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE;QAC/B,SAAS,EAAE,OAAO;QAClB,SAAS,EAAE,iBAAiB;KAC7B,CAAC,CAAC;AACL,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,sBAAsB,CACpC,KAAa,EACb,MAAc;IAEd,IAAI,OAAgB,CAAC;IACrB,IAAI,CAAC;QACH,OAAO,GAAG,GAAG,CAAC,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,UAAU,EAAE,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC;IACjE,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,IAAI,iBAAiB,CACzB,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,2BAA2B,CACjE,CAAC;IACJ,CAAC;IACD,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,EAAE,CAAC;QACxB,MAAM,IAAI,iBAAiB,CAAC,oCAAoC,CAAC,CAAC;IACpE,CAAC;IACD,OAAO;QACL,OAAO,EAAE,OAAO,CAAC,OAAO;QACxB,IAAI,EAAE,OAAO,CAAC,IAAI;QAClB,SAAS,EAAE,OAAO,CAAC,SAAS;QAC5B,OAAO,EAAE,OAAO,CAAC,OAAO;QACxB,cAAc,EAAE,OAAO,CAAC,cAAc;QACtC,IAAI,EAAE,OAAO,CAAC,IAAI;QAClB,QAAQ,EAAE,OAAO,CAAC,QAAQ;KAC3B,CAAC;AACJ,CAAC;AAED,SAAS,SAAS,CAAC,KAAc;IAC/B,IAAI,CAAC,KAAK,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,OAAO,KAAK,CAAC;IACtD,MAAM,CAAC,GAAG,KAAgC,CAAC;IAC3C,OAAO,CACL,OAAO,CAAC,CAAC,OAAO,KAAK,QAAQ;QAC7B,OAAO,CAAC,CAAC,IAAI,KAAK,QAAQ;QAC1B,OAAO,CAAC,CAAC,SAAS,KAAK,QAAQ;QAC/B,OAAO,CAAC,CAAC,OAAO,KAAK,QAAQ;QAC7B,OAAO,CAAC,CAAC,cAAc,KAAK,QAAQ;QACpC,yEAAyE;QACzE,mEAAmE;QACnE,OAAO,CAAC,CAAC,IAAI,KAAK,QAAQ,IAAI,oBAAoB,EAAE,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC;QACrE,OAAO,CAAC,CAAC,QAAQ,KAAK,QAAQ,CAC/B,CAAC;AACJ,CAAC"}

package/dist/services/assets/asset-index-service.d.ts

@@ -0,0 +1,127 @@
+/**
+ * Authoritative ownership index for immutable-keyed assets.
+ *
+ * Assets are stored under an immutable key `{assetId}/{filename}` (assetId =
+ * UUIDv4), so the storage location no longer encodes the owning entity's
+ * mutable `(type, id)`. This table is the single source of truth for:
+ *   - per-repo authorization on the serving route (`repo`), and
+ *   - "which assets does entity E own?" for delete/transfer (`owner_type`,
+ *     `owner_id`).
+ *
+ * It is written authoritatively at upload and updated by every mutation path
+ * (rename/changeType/move/transfer/delete). It is NOT rebuilt from entity
+ * bodies: deriving ownership from user-editable `/api/assets/{id}` embeds would
+ * let a user in repo A claim an asset owned by repo B by pasting its URL —
+ * a privilege-escalation vector. Treat this db as durable critical state
+ * (it lives on the same persistent workspace volume as auth.db / secrets.db),
+ * not a regenerable cache.
+ *
+ * `migration_ledger` is a transient table used only by the one-time
+ * old→new key migration to stay idempotent; it is dropped after cutover.
+ */
+export interface AssetIndexRow {
+    assetId: string;
+    repo: string;
+    ownerType: string;
+    ownerId: string;
+    filename: string;
+    contentType: string;
+    mediaType: string;
+    name: string | null;
+    /** Auth user id (as string) of whoever uploaded the asset, or null for
+     *  rows predating this column / system / agent uploads. Drives the
+     *  "delete restricted to uploader + workspace owner" rule on the workspace
+     *  asset store. NOT an ownership field (that's owner_type/owner_id) — purely
+     *  provenance for delete authz. */
+    uploaderUserId: string | null;
+    /** Caption for the asset (alt-text / OCR / vision description). DB-only and
+     *  durable next to the bytes, so it survives deletion of any entity that
+     *  merely embeds the asset (asset-as-embed model). Populated by the async
+     *  caption pass, not synchronously at upload — null until then. */
+    caption: string | null;
+    /** Byte size of the stored blob. Recorded at upload so the asset manager's
+     *  ownerless listing can show size without resolving an entity (the legacy
+     *  `asset` entity carried `asset_size` in frontmatter; free-standing assets
+     *  carry it here). Null for rows predating this column. */
+    size: number | null;
+    createdAt: string;
+}
+export type AssetIndexInput = Omit<AssetIndexRow, 'createdAt' | 'uploaderUserId' | 'caption' | 'size'> & {
+    createdAt?: string;
+    /** Optional — omit/null when the uploader isn't an identified web user
+     *  (CLI/import/agent). Existing put() callers stay source-compatible. */
+    uploaderUserId?: string | null;
+    /** Optional — set at upload when known (buffer length). Existing callers
+     *  that omit it record null. */
+    size?: number | null;
+};
+/** Owner-reassignment changes for a mutation. Any subset may be supplied. */
+export interface OwnerReassignment {
+    ownerType?: string;
+    ownerId?: string;
+    repo?: string;
+}
+export declare class AssetIndexService {
+    private db;
+    constructor(workspacePath: string);
+    /** Keep assets.db (+ WAL/SHM) out of the workspace config repo — it's
+     *  local, durable on the workspace volume, and not safely rebuildable from
+     *  bodies, so it's never committed. Mirrors auth.db / secrets.db. */
+    private ensureGitignore;
+    /** Insert or replace the row for an assetId (idempotent on re-run).
+     *  `caption` is intentionally NOT in the ON CONFLICT update set: it's
+     *  written later by the async caption pass via `setCaption`, and a re-put
+     *  (e.g. migration) must not clobber an existing caption back to null. */
+    put(input: AssetIndexInput): void;
+    /** Set (or clear) the caption for an asset. Written by the async caption
+     *  pass; isolated from `put` so it never touches ownership/size columns. */
+    setCaption(assetId: string, caption: string | null): void;
+    /** True if `user` may delete the given asset: the original uploader, or a
+     *  workspace owner. Unknown-uploader rows (null) are owner-only. This is the
+     *  D2 rule for the workspace asset store; folder-scoped assets continue to
+     *  use folder write access. `isWorkspaceOwner` is passed in to keep this
+     *  service free of an auth-service dependency. */
+    canDelete(assetId: string, userId: number | undefined, isWorkspaceOwner: boolean): boolean;
+    get(assetId: string): AssetIndexRow | null;
+    /**
+     * Assets owned by `(repo, ownerType, ownerId)`. The `repo` scope is
+     * mandatory: entity ids are unique only within (repo, type), NOT across the
+     * workspace — `note/foo` can exist in two repos. Matching on owner alone
+     * would let a delete/rename in repo A touch repo B's identically-named
+     * entity's assets (cross-repo data loss).
+     */
+    listByOwner(repo: string, ownerType: string, ownerId: string): AssetIndexRow[];
+    listByRepo(repo: string): AssetIndexRow[];
+    /**
+     * Reassign every asset owned by `(repo, fromType, fromId)`. Used by mutations:
+     *   - rename:      reassignOwner(repo, type, oldId, { ownerId: newId })
+     *   - changeType:  reassignOwner(repo, oldType, id, { ownerType: newType })
+     *   - cross-repo move/transfer: reassignOwner(sourceRepo, type, id, { repo: target })
+     * `repo` scopes the match (see listByOwner) — without it a rename in one repo
+     * would reassign a same-named entity's assets in another. Returns rows updated.
+     * No blob movement — keys are immutable.
+     */
+    reassignOwner(repo: string, fromType: string, fromId: string, changes: OwnerReassignment): number;
+    /**
+     * Relocate a single free-standing asset to another folder, addressed by its
+     * immutable assetId (the asset manager's move). No blob movement — the key is
+     * `{assetId}/{filename}`, independent of repo; only the index row's scope
+     * changes. The relocated asset is normalized to folder-owned by its new repo
+     * (ownerType='folder', ownerId=targetRepo) — a free-standing asset's owner IS
+     * its folder, so this keeps the row coherent rather than stranding a stale
+     * owner_type/owner_id in the destination. Returns true if a row was updated.
+     * The caller gates this to free-standing assets.
+     */
+    moveByAssetId(assetId: string, targetRepo: string): boolean;
+    delete(assetId: string): void;
+    ledgerGet(repo: string, oldKey: string): string | null;
+    ledgerPut(repo: string, oldKey: string, assetId: string): void;
+    ledgerEntries(): Array<{
+        repo: string;
+        oldKey: string;
+        assetId: string;
+    }>;
+    dropLedger(): void;
+    close(): void;
+    private toRow;
+}