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

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;
+}

package/dist/services/assets/asset-index-service.js

@@ -0,0 +1,227 @@
+import Database from 'better-sqlite3';
+import { join } from 'node:path';
+import { existsSync, mkdirSync, chmodSync, readFileSync, writeFileSync } from 'node:fs';
+export class AssetIndexService {
+    db;
+    constructor(workspacePath) {
+        const sgDir = join(workspacePath, '.studiograph');
+        if (!existsSync(sgDir))
+            mkdirSync(sgDir, { recursive: true });
+        this.ensureGitignore(sgDir);
+        const dbPath = join(sgDir, 'assets.db');
+        this.db = new Database(dbPath);
+        if (process.platform !== 'win32') {
+            try {
+                chmodSync(dbPath, 0o600);
+            }
+            catch { /* non-fatal */ }
+        }
+        this.db.pragma('journal_mode = WAL');
+        this.db.exec(`
+      CREATE TABLE IF NOT EXISTS assets (
+        asset_id     TEXT PRIMARY KEY,
+        repo         TEXT NOT NULL,
+        owner_type   TEXT NOT NULL,
+        owner_id     TEXT NOT NULL,
+        filename     TEXT NOT NULL,
+        content_type TEXT NOT NULL,
+        media_type   TEXT NOT NULL,
+        name         TEXT,
+        created_at   TEXT NOT NULL DEFAULT (datetime('now'))
+      )
+    `);
+        // Idempotent migration: add uploader_user_id to assets.db tables that
+        // predate it (real workspaces already carry rows). PRAGMA table_info is
+        // the portable "column exists?" check; ALTER ADD COLUMN backfills NULL
+        // for existing rows, which is exactly the "unknown uploader" semantics.
+        const cols = this.db.prepare(`PRAGMA table_info(assets)`).all();
+        if (!cols.some(c => c.name === 'uploader_user_id')) {
+            this.db.exec(`ALTER TABLE assets ADD COLUMN uploader_user_id TEXT`);
+        }
+        // Asset-as-embed: caption + size live next to the bytes (DB-only) so they
+        // survive deletion of any embedding entity. Idempotent ADD COLUMN backfills
+        // NULL for existing rows.
+        if (!cols.some(c => c.name === 'caption')) {
+            this.db.exec(`ALTER TABLE assets ADD COLUMN caption TEXT`);
+        }
+        if (!cols.some(c => c.name === 'size')) {
+            this.db.exec(`ALTER TABLE assets ADD COLUMN size INTEGER`);
+        }
+        this.db.exec(`CREATE INDEX IF NOT EXISTS idx_assets_owner ON assets(owner_type, owner_id)`);
+        this.db.exec(`CREATE INDEX IF NOT EXISTS idx_assets_repo ON assets(repo)`);
+        this.db.exec(`
+      CREATE TABLE IF NOT EXISTS migration_ledger (
+        repo     TEXT NOT NULL,
+        old_key  TEXT NOT NULL,
+        asset_id TEXT NOT NULL,
+        PRIMARY KEY (repo, old_key)
+      )
+    `);
+    }
+    /** 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. */
+    ensureGitignore(sgDir) {
+        const gitignorePath = join(sgDir, '.gitignore');
+        const entries = ['assets.db', 'assets.db-wal', 'assets.db-shm'];
+        let content = '';
+        if (existsSync(gitignorePath))
+            content = readFileSync(gitignorePath, 'utf-8');
+        const missing = entries.filter(e => !content.includes(e));
+        if (missing.length > 0) {
+            const suffix = (content && !content.endsWith('\n') ? '\n' : '') +
+                '# Asset ownership index — local, durable on the workspace volume\n' +
+                missing.join('\n') + '\n';
+            writeFileSync(gitignorePath, content + suffix, 'utf-8');
+        }
+    }
+    /** 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) {
+        this.db.prepare(`
+      INSERT INTO assets (asset_id, repo, owner_type, owner_id, filename, content_type, media_type, name, uploader_user_id, size, created_at)
+      VALUES (@assetId, @repo, @ownerType, @ownerId, @filename, @contentType, @mediaType, @name, @uploaderUserId, @size, COALESCE(@createdAt, datetime('now')))
+      ON CONFLICT(asset_id) DO UPDATE SET
+        repo=excluded.repo, owner_type=excluded.owner_type, owner_id=excluded.owner_id,
+        filename=excluded.filename, content_type=excluded.content_type,
+        media_type=excluded.media_type, name=excluded.name,
+        uploader_user_id=excluded.uploader_user_id, size=excluded.size
+    `).run({
+            assetId: input.assetId,
+            repo: input.repo,
+            ownerType: input.ownerType,
+            ownerId: input.ownerId,
+            filename: input.filename,
+            contentType: input.contentType,
+            mediaType: input.mediaType,
+            name: input.name ?? null,
+            uploaderUserId: input.uploaderUserId ?? null,
+            size: input.size ?? null,
+            createdAt: input.createdAt ?? null,
+        });
+    }
+    /** 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, caption) {
+        this.db.prepare(`UPDATE assets SET caption = ? WHERE asset_id = ?`).run(caption, assetId);
+    }
+    /** 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, userId, isWorkspaceOwner) {
+        if (isWorkspaceOwner)
+            return true;
+        if (userId === undefined)
+            return false;
+        const row = this.get(assetId);
+        if (!row)
+            return false;
+        return row.uploaderUserId === String(userId);
+    }
+    get(assetId) {
+        const row = this.db.prepare(`SELECT * FROM assets WHERE asset_id = ?`).get(assetId);
+        return row ? this.toRow(row) : 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, ownerType, ownerId) {
+        const rows = this.db.prepare(`SELECT * FROM assets WHERE repo = ? AND owner_type = ? AND owner_id = ? ORDER BY created_at`).all(repo, ownerType, ownerId);
+        return rows.map(r => this.toRow(r));
+    }
+    listByRepo(repo) {
+        const rows = this.db.prepare(`SELECT * FROM assets WHERE repo = ? ORDER BY created_at`).all(repo);
+        return rows.map(r => this.toRow(r));
+    }
+    /**
+     * 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, fromType, fromId, changes) {
+        const sets = [];
+        // Distinct param names: @matchRepo scopes the WHERE; @newRepo is the SET.
+        // Sharing one `@repo` would let a repo-change overwrite the match value.
+        const params = { matchRepo: repo, fromType, fromId };
+        if (changes.ownerType !== undefined) {
+            sets.push('owner_type = @ownerType');
+            params.ownerType = changes.ownerType;
+        }
+        if (changes.ownerId !== undefined) {
+            sets.push('owner_id = @ownerId');
+            params.ownerId = changes.ownerId;
+        }
+        if (changes.repo !== undefined) {
+            sets.push('repo = @newRepo');
+            params.newRepo = changes.repo;
+        }
+        if (sets.length === 0)
+            return 0;
+        const res = this.db.prepare(`UPDATE assets SET ${sets.join(', ')} WHERE repo = @matchRepo AND owner_type = @fromType AND owner_id = @fromId`).run(params);
+        return res.changes;
+    }
+    /**
+     * 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, targetRepo) {
+        const res = this.db.prepare(`UPDATE assets SET repo = @repo, owner_type = 'folder', owner_id = @repo WHERE asset_id = @assetId`).run({ repo: targetRepo, assetId });
+        return res.changes > 0;
+    }
+    delete(assetId) {
+        this.db.prepare(`DELETE FROM assets WHERE asset_id = ?`).run(assetId);
+    }
+    // ── migration ledger (transient; dropped post-cutover) ───────────────────
+    ledgerGet(repo, oldKey) {
+        const row = this.db.prepare(`SELECT asset_id FROM migration_ledger WHERE repo = ? AND old_key = ?`).get(repo, oldKey);
+        return row ? row.asset_id : null;
+    }
+    ledgerPut(repo, oldKey, assetId) {
+        this.db.prepare(`INSERT OR IGNORE INTO migration_ledger (repo, old_key, asset_id) VALUES (?, ?, ?)`).run(repo, oldKey, assetId);
+    }
+    ledgerEntries() {
+        const rows = this.db.prepare(`SELECT repo, old_key, asset_id FROM migration_ledger`).all();
+        return rows.map(r => ({ repo: r.repo, oldKey: r.old_key, assetId: r.asset_id }));
+    }
+    dropLedger() {
+        this.db.exec(`DROP TABLE IF EXISTS migration_ledger`);
+    }
+    close() {
+        this.db.close();
+    }
+    toRow(r) {
+        return {
+            assetId: r.asset_id,
+            repo: r.repo,
+            ownerType: r.owner_type,
+            ownerId: r.owner_id,
+            filename: r.filename,
+            contentType: r.content_type,
+            mediaType: r.media_type,
+            name: r.name ?? null,
+            uploaderUserId: r.uploader_user_id ?? null,
+            caption: r.caption ?? null,
+            size: r.size ?? null,
+            createdAt: r.created_at,
+        };
+    }
+}
+//# sourceMappingURL=asset-index-service.js.map

package/dist/services/assets/asset-index-service.js.map

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

package/dist/services/assets/base.d.ts

@@ -9,6 +9,15 @@ export interface AssetInfo {
     path: string;
     mediaType: 'image' | 'video' | 'audio' | 'document' | 'other';
 }
+/**
+ * Assets enumerated across the whole backend with their (type, id) origin
+ * parsed out of the storage key. Used by the asset manager to avoid
+ * per-entity round-trips.
+ */
+export interface AssetRecord extends AssetInfo {
+    entityType: string;
+    entityId: string;
+}
 export interface AssetBackend {
     /**
      * Upload asset to storage
@@ -18,6 +27,26 @@ export interface AssetBackend {
      * List assets with a given prefix
      */
     list(prefix: string): Promise<AssetInfo[]>;
+    /**
+     * List every asset under the backend's root, parsed into
+     * `{type}/{id}/{filename}` components. Single round-trip for R2 (via
+     * paginated ListObjectsV2), single filesystem walk for local. Used by
+     * the asset manager to enumerate without per-entity queries.
+     */
+    listAll(): Promise<AssetRecord[]>;
+    /**
+     * Download an object's bytes into a Buffer. Used by server-side consumers
+     * that need the actual content (e.g. converting a stored .docx/.xlsx to a
+     * derived note/dataset). Throws when the key doesn't exist. Both backends
+     * implement it — local reads from disk, R2 issues a GetObject.
+     */
+    download(key: string): Promise<Buffer>;
+    /**
+     * Server-side copy from one key to another (no download round-trip).
+     * Used by the asset re-key migration and cross-repo transfer-copy.
+     * Overwrites the destination if it exists (idempotent re-runs).
+     */
+    copy(srcKey: string, destKey: string): Promise<void>;
     /**
      * Delete a single asset
      */
@@ -30,6 +59,51 @@ export interface AssetBackend {
      * Check if an asset exists
      */
     exists(key: string): Promise<boolean>;
+    /**
+     * Generate a short-lived pre-signed URL for a stored object.
+     * Implemented by remote backends (R2/S3); local backend leaves this
+     * undefined since files are streamed directly by the HTTP server.
+     * `method` selects the HTTP verb the URL is signed against.
+     */
+    getSignedUrl?(key: string, expiresIn?: number, method?: 'GET' | 'HEAD'): Promise<string>;
+    /**
+     * Generate a short-lived pre-signed URL the *client* can PUT to directly,
+     * bypassing the app server. Implemented by remote backends (R2/S3) so
+     * external agents can upload large binaries without bytes passing through
+     * the API. `contentType` is pinned into the signature so the client must
+     * send a matching `Content-Type` header; the returned `headers` map tells
+     * the client which headers to set verbatim.
+     */
+    getSignedPutUrl?(key: string, contentType: string, expiresIn?: number): Promise<{
+        uploadUrl: string;
+        headers: Record<string, string>;
+    }>;
+    /**
+     * Fetch object metadata without downloading bytes. Returns `null` when
+     * the key doesn't exist (matches HEAD 404 semantics). The MCP finalize
+     * flow uses this to verify the agent's PUT actually landed AND that the
+     * stored `Content-Type` + `Content-Length` match the pre-signed contract
+     * before promoting `pending/` → canonical. Remote-only.
+     */
+    head?(key: string): Promise<{
+        contentType: string;
+        size: number;
+    } | null>;
+    /**
+     * Bucket-level object-lifecycle rules summarized into a flat list of
+     * `{ prefix, expirationDays, enabled }`. Used by the MCP presign flow's
+     * boot-time backstop (asset-lifecycle-check) to confirm the operator has
+     * configured the `pending/` quarantine rule. `enabled` reflects the S3
+     * `Status` field — a disabled rule does not fire even if its prefix and
+     * TTL look right, so callers must check `enabled` before treating a rule
+     * as covering anything. `null` when the bucket has no lifecycle
+     * configuration at all. Remote-only — local FS has no notion of lifecycle.
+     */
+    getBucketLifecycle?(): Promise<Array<{
+        prefix: string | undefined;
+        expirationDays: number | undefined;
+        enabled: boolean;
+    }> | null>;
 }
 export interface AssetConfig {
     storage: 'local' | 'r2';
@@ -44,17 +118,60 @@ export interface R2Config {
     secretAccessKey: string;
 }
 /**
- * Content type mappings
+ * Content type mappings.
+ *
+ * TODO(import-refactor): this map + `detectAssetKind` are a second source of
+ * truth for per-extension MIME / kind alongside the format registry
+ * (`src/core/format-registry.ts`, which owns `mimeTypes`). Folding them into
+ * the registry is deferred because it would change observable behavior the
+ * P0 parity refactor must preserve (e.g. svg's asset_kind `other`→`image`,
+ * tsv's Content-Type `octet-stream`→`text/tab-separated-values`). Until that
+ * unification lands, `format-registry.test.ts` guards the two against drift
+ * on every shared extension.
  */
 export declare const CONTENT_TYPES: Record<string, string>;
 /**
  * Detect content type from filename
  */
 export declare function detectContentType(filename: string): string;
+import type { AssetKind } from '../../core/validation.js';
+/**
+ * Map a filename to the high-level `asset_kind` written into the asset
+ * entity's frontmatter. Drives icon and viewer selection; coarser than
+ * MIME so the UI doesn't need to enumerate every format. The kind set
+ * is canonical in `ASSET_KINDS` in src/core/validation.ts.
+ */
+export declare function detectAssetKind(filename: string): AssetKind;
+/**
+ * Extension set the asset upload route accepts (bare, no leading dot).
+ *
+ * The format registry (`src/core/format-registry.ts`) is the single source
+ * of truth for this set — it owns the canonical disposition of every format.
+ * This re-export keeps `isAssetUploadExtension` and the (untouched) agent
+ * `import_file` tool working against the same data, with no parallel list to
+ * drift. The registry's `assetUploadExtensions()` reproduces the historical
+ * membership exactly (including `.csv`, which the agent tool stores as an
+ * opaque asset even though the web path writes it as a dataset).
+ */
+export declare const ASSET_UPLOAD_EXTENSIONS: Set<string>;
+export declare function isAssetUploadExtension(filename: string): boolean;
 /**
  * Determine media type from content type
  */
 export declare function getMediaType(contentType: string): AssetInfo['mediaType'];
+/**
+ * Sanitize a filename for use as a storage key segment.
+ *
+ * Replaces every character that's not `[a-zA-Z0-9._-]` with `_`. Preserves
+ * the extension via the `.` allowlist; preserves common separators (`_` and
+ * `-`) so display titles derived from the slug stay readable.
+ *
+ * NOT a security boundary — `validateFilename()` above is the gate that
+ * throws on traversal / hidden / forbidden chars / length. `safeFilename`
+ * is the post-validation key builder. Promoted from
+ * `asset-sidecar-service.ts` so the MCP presign flow can share it.
+ */
+export declare function safeFilename(name: string): string;
 /**
  * Validate filename for security
  */