@flowdular/sdk 0.2.4 → 0.3.1

package/modules/documents/spec/module.yaml

@@ -0,0 +1,248 @@
+schemaVersion: 2
+id: documents.core
+specVersion: 0.1.9
+status: approved
+name: Documents Core
+description: Lets a workspace attach files to its records through the platform storage port, owning only the document metadata and the reference to the record, with tenant-scoped keys, encrypted bytes, size and type limits, and a scan state, so a module attaches by reference and never holds bytes.
+profile: full
+capabilities:
+  - api
+  - database
+  - client
+  - translations
+  - cli
+dependencies:
+  - id: system.core
+    range: ^0.7.0
+  - id: auth.core
+    range: ^0.13.0
+tenancy: required
+locales:
+  - en
+  - pl
+invariants:
+  - Persistence runs on the shared asynchronous database contract with explicit PostgreSQL SQL; every tenant table enables and forces row-level security with USING and WITH CHECK policies bound to the transaction-local tenant id, and the runtime role holds neither SUPERUSER nor BYPASSRLS.
+  - Bytes live only in the platform storage port under a key whose first segment is the tenant id taken from the principal; documents.core stores metadata and never a byte, and a module attaches a document to its record by reference through the public capability documents.attachments.v1, never by reading the store. The capability offers list, open and delete on that reference; open streams the decrypted bytes through documents.core's own storage access and answers nothing for a reference with no readable object behind it, an infected or deleted document included, so the storage key never leaves this module.
+  - An upload is one request whose body is the file, bounded by the platform object limit, with the declared content type checked against the platform allowlist and the magic bytes before the object is stored; a refusal leaves no metadata row and no object.
+  - A download is a short-lived signed read URL from the storage port; documents.core serves no route that streams bytes, and the URL is issued only to a principal allowed to read the owning record's documents.
+  - The scan state follows the storage port's verdict; an infected object is deleted from the store immediately, its row keeps the infected state for the audit trail, and it can never be downloaded; an unscanned object is downloadable and labelled as such.
+  - Deleting a document deletes the object first and the row after; a document referenced by a record is deleted only through the owning module's capability call or by a member holding documents.files.manage.
+  - Every workspace has a storage quota setting; an upload that would exceed it is refused with a stable error before any byte is stored.
+  - The document list is filtered, searched and paged by the server. The owner module, the record reference, the scan verdict and the screen's search term narrow the query; the term travels as the bounded query parameter q, matches the filename or the description, and reaches SQL as a parameter whose LIKE wildcards are escaped, so a wildcard a reader types searches for that character. The page is a keyset cursor the module signs with a secret of its own process, so a cursor issued by one replica is refused by another with CURSOR_INVALID and the client starts over. The screen shows either a real total or that more rows remain, and never narrows or pages the rows of one answer as if they were the workspace.
+  - Upload metadata travels in headers, which carry ASCII only, so a value holding a code point above 0x7F is refused and a client percent-encodes it; a name is stored as it was sent or not at all.
+  - The object ceiling and the accepted content types are served to the screen, which states them and refuses a file past the ceiling before it sends one. The storage port stays the authority on both and refuses again on the bytes it receives.
+  - Documents are a data class declared through the platform data class registry, exportable as metadata rows that name the storage key while the bytes stay in the object store until the export sink gains an attachment channel, and swept only by explicit deletion, never by retention.
+permissions:
+  - id: documents.files.read
+    description: List documents of the active workspace and obtain read URLs for them.
+  - id: documents.files.manage
+    description: Upload, replace and delete documents in the active workspace.
+dataOwnership:
+  - documents.core owns document metadata, the storage key, the checksum, the scan state and the attachment reference.
+  - The platform storage port owns the bytes and their encryption; the owning module owns the record a document is attached to and decides through its own permissions who may see the record.
+entities:
+  - id: document
+    name: Document
+    description: One stored file and the record it is attached to.
+    fields:
+      - id: ownerModule
+        type: string
+        required: true
+        maxLength: 64
+      - id: recordRef
+        type: string
+        required: true
+        maxLength: 200
+      - id: filename
+        type: string
+        required: true
+        maxLength: 255
+      - id: contentType
+        type: string
+        required: true
+        maxLength: 128
+      - id: bytes
+        type: integer
+        required: true
+      - id: checksum
+        type: string
+        required: false
+        maxLength: 80
+        description: The port's algorithm-prefixed digest; absent for a refused infected upload that left no object.
+      - id: storageKey
+        type: string
+        required: true
+        maxLength: 512
+      - id: uploaderAccountId
+        type: string
+        required: true
+        maxLength: 128
+      - id: scan
+        type: enum
+        required: true
+        values:
+          - unscanned
+          - clean
+          - infected
+      - id: status
+        type: enum
+        required: true
+        values:
+          - stored
+          - deleted
+      - id: description
+        type: text
+        required: false
+        maxLength: 1000
+    states:
+      field: status
+      values:
+        - stored
+        - deleted
+      transitions:
+        - from: stored
+          to: deleted
+          permission: documents.files.manage
+screens:
+  - id: documents
+    kind: list
+    entity: document
+    title: Documents
+    columns:
+      - filename
+      - ownerModule
+      - recordRef
+      - contentType
+      - bytes
+      - scan
+      - uploaderAccountId
+    filters:
+      - ownerModule
+      - scan
+      - filename
+      - description
+    navigationGroup: Workspace
+actions:
+  - id: upload
+    entity: document
+    permission: documents.files.manage
+    kind: create
+    risk: workspace-write
+    idempotent: false
+    description: Store one file for a record reference; refused over the object limit, outside the allowlist, on a magic-byte mismatch or over the workspace quota.
+  - id: read-limits
+    entity: document
+    permission: documents.files.read
+    kind: custom
+    risk: read
+    idempotent: true
+    description: Answer the platform object ceiling and the accepted content types, so the uploader states them and refuses a file before it is sent.
+  - id: read-url
+    entity: document
+    permission: documents.files.read
+    kind: custom
+    risk: read
+    idempotent: true
+    description: Issue a signed read URL valid for a bounded number of seconds; refused for an infected document.
+  - id: delete
+    entity: document
+    permission: documents.files.manage
+    kind: delete
+    risk: destructive
+    idempotent: true
+    description: Delete the object, then mark the row deleted.
+  - id: delete-many
+    entity: document
+    permission: documents.files.manage
+    kind: delete
+    risk: destructive
+    idempotent: true
+    description: Delete the documents the screen selected, between 1 and 100 unique ids, each through the single delete path, answering one outcome per id (deleted, not-found or refused) and never failing the whole call for a missing id.
+widgets: []
+settings:
+  - key: quotaBytes
+    type: integer
+    scope: tenant
+    default: 10737418240
+    description: Storage quota of the workspace in bytes; 0 means no uploads.
+  - key: readUrlSeconds
+    type: integer
+    scope: platform
+    default: 300
+    description: Lifetime of a read URL; 30 to 3600.
+agentTools: []
+outOfScope:
+  - Previews, thumbnails and in-browser rendering are not offered; a document is downloaded.
+  - Versioning of a document is not offered; replacing is an upload plus a delete by the owning module.
+  - A shared FileUpload component does not exist yet; the Documents screen builds its uploader locally and flags it as a promotion candidate.
+  - Malware scanning runs only when the deployment configures a scanner for the storage port; otherwise documents are labelled unscanned.
+decisions:
+  - id: D-DOCUMENTS-STORAGE
+    question: Where do bytes live?
+    answer: In the platform storage port with a local adapter for development and an S3-compatible adapter for deployments, encrypted under the storage keyring.
+    decidedBy: user
+  - id: D-DOCUMENTS-LIMITS
+    question: What limits apply?
+    answer: 25 MB per object by default, a content type allowlist with magic-byte verification, a scanner hook, and a 10 GB workspace quota by default.
+    decidedBy: user
+  - id: D-DOCUMENTS-ATTACH
+    question: How does a module attach a file?
+    answer: By reference through documents.attachments.v1, naming its module id and record reference; the module never holds bytes.
+    decidedBy: default
+  - id: D-DOCUMENTS-INFECTED
+    question: What happens to an infected file?
+    answer: The object is deleted at once, the row stays infected for the trail, and a download is refused.
+    decidedBy: default
+  - id: D-DOCUMENTS-PERMISSIONS
+    question: Who reads and manages documents?
+    answer: Members hold documents.files.read and documents.files.manage by default; the owning module may narrow through its own record permissions.
+    decidedBy: default
+  - id: D-DOCUMENTS-ATTACH-AUTHORITY
+    question: Who may attach a file to another module's record?
+    answer: Attaching is workspace-wide under documents.files.manage. documents.core holds no per-module attach predicate and does not ask the owning module whether the reference it was given is a record at all, so any member who may upload may name any owner module and record reference. An owning module narrows on read alone, through the capability, where its own record permission decides who sees an attachment. A per-module attach predicate stays out of scope until a module needs to refuse a reference at upload time.
+    decidedBy: default
+acceptanceScenarios:
+  - id: DOCUMENTS-UPLOAD
+    given: A principal holding documents.files.manage uploads a PDF under the object limit for a record reference.
+    when: The upload completes.
+    then: The object is stored encrypted under a key whose first segment is the principal's tenant, a metadata row records filename, content type, bytes, checksum, uploader and scan state, and the response carries the document id.
+  - id: DOCUMENTS-REFUSE
+    given: A principal uploads a file over the object limit, an executable, a file whose magic bytes do not match its declared type, or a file that would exceed the workspace quota.
+    when: The upload is attempted.
+    then: Each is refused with a stable error before any byte is stored and no row is written.
+  - id: DOCUMENTS-READ-URL
+    given: A stored document.
+    when: A principal holding documents.files.read requests a read URL, waits past its lifetime, and requests one for an infected document.
+    then: The first URL streams the decrypted bytes with the stored content type, the expired URL answers not found, and the infected document is refused.
+  - id: DOCUMENTS-ATTACH-BY-REFERENCE
+    given: A module holds a record and a document id.
+    when: The module lists documents for its record reference through documents.attachments.v1 and deletes one.
+    then: Only documents of that module and reference in the caller's tenant are returned, the delete removes the object first and marks the row, and a document of another module or tenant is not visible.
+  - id: DOCUMENTS-OPEN
+    given: A module owns a record with a stored document, another module names the same document id under its own reference pair, and the record also holds an infected document.
+    when: Each of them is opened through documents.attachments.v1.
+    then: The owning module's own reference streams the decrypted bytes with the stored content type, byte count and filename and no storage key, the other module's reference pair answers nothing, and the infected document answers nothing as well.
+  - id: DOCUMENTS-PAGE
+    given: A workspace holding more documents than one page carries, some of them another module's.
+    when: A screen lists them with a page limit, follows the cursor it receives to the end, filters on the owner module, searches a term the filename or the description carries, and presents a cursor this server did not sign.
+    then: Every row is answered exactly once across the pages, the cursor is null on the last one, the owner module filter and the search term are applied by the query rather than by the screen, the term pages with the cursor, a term that is only a LIKE wildcard matches nothing instead of the workspace, a term past its bound is refused, and the forged cursor is refused with CURSOR_INVALID.
+  - id: DOCUMENTS-HEADER-ASCII
+    given: A client uploading a file whose name is not ASCII.
+    when: The name travels raw in the header and, on a second attempt, percent-encoded.
+    then: The raw value is refused before any byte is stored, and the percent-encoded one is stored and read back as the name that was sent.
+  - id: DOCUMENTS-LIMITS
+    given: A principal holding documents.files.read.
+    when: The screen asks for the upload limits.
+    then: The platform object ceiling and the accepted content types are answered, an unauthenticated request is refused, and the uploader refuses a larger file before it sends one.
+  - id: DOCUMENTS-DELETE-MANY
+    given: A principal holding documents.files.manage selects several stored documents, and the request also names an id that does not exist and one that belongs to another workspace.
+    when: The principal deletes them in one call naming the selected ids.
+    then: A list of no ids, of more than 100, or one repeating an id is refused with INVALID_INPUT before any row is touched; otherwise each named row of the workspace is deleted through the single delete path, so its object is removed first and its row is kept as the deleted trail, the missing and the foreign id are answered not-found with nothing else deleted, the response carries one outcome per id in the order sent, and a call without the permission or the CSRF proof is refused first.
+  - id: DOCUMENTS-DENY
+    given: A principal is unauthenticated or lacks the required permission.
+    when: The principal uploads, lists, requests a read URL or deletes.
+    then: The server denies the operation before repository access, and a mutation without a CSRF proof is refused first.
+  - id: DOCUMENTS-TENANT-BOUNDARY
+    given: Two workspaces with documents.
+    when: A runtime transaction bound to one workspace reads or writes rows, or a read URL of one workspace is presented for the other's object.
+    then: Only that workspace's rows are visible or mutable, the storage key prefix keeps the objects apart, and the foreign URL answers not found.

package/modules/documents/src/acl/permissions.ts

@@ -0,0 +1,6 @@
+export const DOCUMENTS_PERMISSIONS = {
+	read: 'documents.files.read',
+	manage: 'documents.files.manage',
+} as const;
+
+export const permissions = Object.freeze(Object.values(DOCUMENTS_PERMISSIONS));

package/modules/documents/src/api/endpoints.ts

@@ -0,0 +1,401 @@
+import { randomBytes } from 'node:crypto';
+import {
+	decodeCursor,
+	defineEndpoint,
+	encodeCursor,
+	HttpProblem,
+	jsonResponse,
+	pageResponse,
+	problemResponse,
+	readJsonObject,
+	readPageQuery,
+	requiredString,
+} from '@flowdular/sdk/server';
+import { STORAGE_CONTENT_TYPES } from '@flowdular/sdk/storage';
+import type { AuthRuntime } from '@flowdular/sdk/modules/auth/server';
+import {
+	endpointIdentityFromContext,
+	principalFromContext,
+	sessionMutationDenial,
+} from '@flowdular/sdk/modules/auth/server';
+import { DOCUMENTS_PERMISSIONS } from '../acl/permissions.ts';
+import {
+	DOCUMENT_LIMITS,
+	DOCUMENT_SCANS,
+	type DocumentScan,
+} from '../domain/types.ts';
+import type { DocumentsRuntime } from '../server/runtime.ts';
+import {
+	documentAttachment,
+	DocumentsServiceError,
+} from '../services/documents-service.ts';
+
+/**
+ * The upload carries the file as the whole body, so everything about it travels
+ * in headers: `content-type` is the declared type the storage port verifies
+ * against the bytes, and these three name the record it belongs to.
+ */
+export const UPLOAD_HEADERS = {
+	filename: 'x-document-filename',
+	ownerModule: 'x-document-owner-module',
+	recordRef: 'x-document-record-ref',
+	description: 'x-document-description',
+} as const;
+
+/* A header travels as ASCII, so anything else is percent encoded. A plain value
+   decodes to itself; a malformed escape is a rejection rather than a guess. */
+const HEADER_RAW_LIMIT = 4_096;
+
+/** The default page of the documents screen, and the ceiling it may ask for. */
+const LIST_PAGE_LIMIT = 50;
+
+function failure(error: unknown): Response {
+	if (error instanceof DocumentsServiceError) {
+		return jsonResponse(
+			{ error: { code: error.code, message: error.message } },
+			error.status,
+		);
+	}
+	return problemResponse(error, 'The documents operation failed.');
+}
+
+function invalid(message: string): HttpProblem {
+	return new HttpProblem('INVALID_INPUT', message, 400);
+}
+
+function headerValue(
+	request: Request,
+	name: string,
+	max: number,
+): string | null {
+	const raw = request.headers.get(name);
+	if (raw === null || raw.trim() === '') return null;
+	if (raw.length > HEADER_RAW_LIMIT) throw invalid(`${name} is too long.`);
+	/* Only a client that percent-encodes reaches this module with a name the
+	   whole way intact: a byte above 0x7F in a header value is read as Latin-1
+	   by one hop and as UTF-8 by the next, so the value that arrives is not the
+	   value that was sent. It is refused rather than stored mangled. */
+	for (let index = 0; index < raw.length; index += 1) {
+		if (raw.charCodeAt(index) > 0x7f) {
+			throw invalid(`${name} must be percent-encoded ASCII.`);
+		}
+	}
+	let decoded: string;
+	try {
+		decoded = decodeURIComponent(raw);
+	} catch {
+		throw invalid(`${name} is not percent-encoded text.`);
+	}
+	const normalized = decoded.trim();
+	if (normalized.length === 0) return null;
+	if (normalized.length > max) throw invalid(`${name} is too long.`);
+	return normalized;
+}
+
+function requiredHeader(request: Request, name: string, max: number): string {
+	const value = headerValue(request, name, max);
+	if (value === null) throw invalid(`${name} is required.`);
+	return value;
+}
+
+/* The declared length refuses an oversized or over-quota body before it is
+   read; the port and the quota check measure what actually arrived. */
+function declaredBytes(request: Request): number | undefined {
+	const raw = request.headers.get('content-length');
+	if (raw === null || raw.trim() === '') return undefined;
+	const value = Number(raw);
+	if (!Number.isSafeInteger(value) || value < 0) {
+		throw invalid('content-length must be a byte count.');
+	}
+	return value;
+}
+
+/* One outcome answers one row, so an id is named once; the count and each id
+   are bounded like the single delete's. */
+function requiredIds(
+	value: Record<string, unknown>,
+	key: string,
+): readonly string[] {
+	const raw = value[key];
+	if (!Array.isArray(raw)) throw invalid(`${key} must be an array.`);
+	if (raw.length < 1 || raw.length > DOCUMENT_LIMITS.deleteMany) {
+		throw invalid(
+			`${key} must name between 1 and ${DOCUMENT_LIMITS.deleteMany} documents.`,
+		);
+	}
+	const ids = raw.map((entry) =>
+		requiredString({ id: entry }, 'id', { max: DOCUMENT_LIMITS.id }),
+	);
+	if (new Set(ids).size !== ids.length) {
+		throw invalid(`${key} must not repeat an id.`);
+	}
+	return ids;
+}
+
+function queryValue(
+	request: Request,
+	key: string,
+	max: number,
+): string | undefined {
+	const raw = new URL(request.url).searchParams.get(key);
+	if (raw === null || raw === '') return undefined;
+	if (raw.length > max) throw invalid(`${key} is too long.`);
+	return raw;
+}
+
+function queryScan(request: Request): DocumentScan | undefined {
+	const raw = queryValue(request, 'scan', 32);
+	if (raw === undefined) return undefined;
+	if (!(DOCUMENT_SCANS as readonly string[]).includes(raw)) {
+		throw invalid(`scan must be one of: ${DOCUMENT_SCANS.join(', ')}.`);
+	}
+	return raw as DocumentScan;
+}
+
+export interface DocumentsRoutesOptions {
+	/**
+	 * The platform object ceiling, so the uploader can refuse a file before it
+	 * sends it. The storage port stays the authority; this is what the screen is
+	 * told about it.
+	 */
+	readonly maxObjectBytes: number;
+}
+
+export function createDocumentsRoutes(
+	auth: AuthRuntime,
+	runtime: DocumentsRuntime,
+	options: DocumentsRoutesOptions,
+) {
+	/* Module-owned and never stored: a cursor names a position in one
+	   workspace's own list, so a restart invalidating one costs a client the
+	   first page. */
+	const cursorSecret = randomBytes(32);
+	const upload = defineEndpoint({
+		id: 'documents.files.upload',
+		path: '/api/documents/upload',
+		methods: ['POST'],
+		access: { kind: 'permission', permission: DOCUMENTS_PERMISSIONS.manage },
+		resolveIdentity: endpointIdentityFromContext,
+		handler: async ({ octane }) => {
+			const denial = sessionMutationDenial(octane, auth);
+			if (denial) return denial;
+			try {
+				const request = octane.request;
+				const contentType = request.headers.get('content-type');
+				if (!contentType) {
+					throw new HttpProblem(
+						'CONTENT_TYPE_REQUIRED',
+						'The declared content type is required.',
+						415,
+					);
+				}
+				const body = request.body;
+				if (!body) throw invalid('The request body is required.');
+				const principal = principalFromContext(octane)!;
+				const service = await runtime.service();
+				const record = await service.upload(
+					principal.tenantId,
+					principal.accountId,
+					{
+						ownerModule: requiredHeader(
+							request,
+							UPLOAD_HEADERS.ownerModule,
+							DOCUMENT_LIMITS.ownerModule,
+						),
+						recordRef: requiredHeader(
+							request,
+							UPLOAD_HEADERS.recordRef,
+							DOCUMENT_LIMITS.recordRef,
+						),
+						filename: requiredHeader(
+							request,
+							UPLOAD_HEADERS.filename,
+							DOCUMENT_LIMITS.filename,
+						),
+						description: headerValue(
+							request,
+							UPLOAD_HEADERS.description,
+							DOCUMENT_LIMITS.description,
+						),
+						contentType,
+						declaredBytes: declaredBytes(request),
+						body,
+					},
+				);
+				return jsonResponse({ document: documentAttachment(record) }, 201);
+			} catch (error) {
+				return failure(error);
+			}
+		},
+	});
+
+	const list = defineEndpoint({
+		id: 'documents.files.list',
+		path: '/api/documents',
+		methods: ['GET'],
+		access: { kind: 'permission', permission: DOCUMENTS_PERMISSIONS.read },
+		resolveIdentity: endpointIdentityFromContext,
+		handler: async ({ octane }) => {
+			try {
+				const service = await runtime.service();
+				const page = readPageQuery(new URL(octane.request.url), {
+					maxLimit: DOCUMENT_LIMITS.page,
+					defaultLimit: LIST_PAGE_LIMIT,
+				});
+				const cursor = page.cursor
+					? decodeCursor(page.cursor, cursorSecret)
+					: null;
+				const records = await service.list(
+					principalFromContext(octane)!.tenantId,
+					{
+						ownerModule: queryValue(
+							octane.request,
+							'ownerModule',
+							DOCUMENT_LIMITS.ownerModule,
+						),
+						recordRef: queryValue(
+							octane.request,
+							'recordRef',
+							DOCUMENT_LIMITS.recordRef,
+						),
+						scan: queryScan(octane.request),
+						/* The screen's search box. It narrows the query, so a term and
+						   a cursor answer one result set rather than a page the screen
+						   would have to search again. */
+						search: queryValue(octane.request, 'q', DOCUMENT_LIMITS.search),
+					},
+					{
+						limit: page.limit,
+						after:
+							cursor === null
+								? null
+								: {
+										createdAt: Number(cursor.createdAt),
+										id: String(cursor.id),
+									},
+					},
+				);
+				const last = records.at(-1);
+				return pageResponse({
+					items: records.map(documentAttachment),
+					limit: page.limit,
+					/* A full page may still be the last one; the client stops when the
+					   cursor stops, which costs one empty page at most. */
+					nextCursor:
+						last && records.length === page.limit
+							? encodeCursor(
+									{ createdAt: last.createdAt, id: last.id },
+									cursorSecret,
+								)
+							: null,
+				});
+			} catch (error) {
+				return failure(error);
+			}
+		},
+	});
+
+	/* What the uploader has to know before it sends a byte. The port applies
+	   both rules itself; a screen that knows them refuses a file the reader
+	   picked instead of spending the upload to find out. */
+	const limits = defineEndpoint({
+		id: 'documents.files.limits',
+		path: '/api/documents/limits',
+		methods: ['GET'],
+		access: { kind: 'permission', permission: DOCUMENTS_PERMISSIONS.read },
+		resolveIdentity: endpointIdentityFromContext,
+		handler: async () =>
+			jsonResponse({
+				maxObjectBytes: options.maxObjectBytes,
+				contentTypes: STORAGE_CONTENT_TYPES,
+			}),
+	});
+
+	const readUrl = defineEndpoint({
+		id: 'documents.files.read-url',
+		path: '/api/documents/read-url',
+		methods: ['POST'],
+		access: { kind: 'permission', permission: DOCUMENTS_PERMISSIONS.read },
+		resolveIdentity: endpointIdentityFromContext,
+		handler: async ({ octane }) => {
+			const denial = sessionMutationDenial(octane, auth);
+			if (denial) return denial;
+			try {
+				const value = await readJsonObject(octane.request);
+				const service = await runtime.service();
+				return jsonResponse(
+					await service.readUrl(
+						principalFromContext(octane)!.tenantId,
+						requiredString(value, 'id', { max: DOCUMENT_LIMITS.id }),
+					),
+				);
+			} catch (error) {
+				return failure(error);
+			}
+		},
+	});
+
+	const remove = defineEndpoint({
+		id: 'documents.files.delete',
+		path: '/api/documents/delete',
+		methods: ['POST'],
+		access: { kind: 'permission', permission: DOCUMENTS_PERMISSIONS.manage },
+		resolveIdentity: endpointIdentityFromContext,
+		handler: async ({ octane }) => {
+			const denial = sessionMutationDenial(octane, auth);
+			if (denial) return denial;
+			try {
+				const value = await readJsonObject(octane.request);
+				const service = await runtime.service();
+				const record = await service.remove(
+					principalFromContext(octane)!.tenantId,
+					requiredString(value, 'id', { max: DOCUMENT_LIMITS.id }),
+				);
+				return jsonResponse({ document: documentAttachment(record) });
+			} catch (error) {
+				return failure(error);
+			}
+		},
+	});
+
+	const removeMany = defineEndpoint({
+		id: 'documents.files.delete-many',
+		path: '/api/documents/delete-many',
+		methods: ['POST'],
+		access: { kind: 'permission', permission: DOCUMENTS_PERMISSIONS.manage },
+		resolveIdentity: endpointIdentityFromContext,
+		handler: async ({ octane }) => {
+			const denial = sessionMutationDenial(octane, auth);
+			if (denial) return denial;
+			try {
+				const value = await readJsonObject(octane.request);
+				const service = await runtime.service();
+				const outcomes = await service.removeMany(
+					principalFromContext(octane)!.tenantId,
+					requiredIds(value, 'ids'),
+				);
+				return jsonResponse({ outcomes });
+			} catch (error) {
+				return failure(error);
+			}
+		},
+	});
+
+	return [
+		upload.serverRoute,
+		list.serverRoute,
+		limits.serverRoute,
+		readUrl.serverRoute,
+		remove.serverRoute,
+		removeMany.serverRoute,
+	] as const;
+}
+
+export const endpoints = [
+	'documents.files.upload',
+	'documents.files.list',
+	'documents.files.limits',
+	'documents.files.read-url',
+	'documents.files.delete',
+	'documents.files.delete-many',
+] as const;

package/modules/documents/src/cli/commands.json

@@ -0,0 +1,17 @@
+{
+	"protocolVersion": 1,
+	"moduleId": "documents.core",
+	"commands": [
+		{
+			"path": ["documents", "secrets-rotate"],
+			"capability": {
+				"id": "documents.storage.rotate",
+				"version": 1,
+				"summary": "Re-seal stored document objects with the current storage encryption key.",
+				"risk": "process",
+				"requiresApprovedSpec": false,
+				"supportsDryRun": true
+			}
+		}
+	]
+}