@flowdular/sdk 0.3.0 → 0.3.1

package/packages/storage/src/envelope.ts

@@ -121,30 +121,30 @@ function describe(key: string, header: FrameHeader): StoredObject {
 	};
 }
 
-export function encodeStoredObject(
+interface FrameDraft {
+	readonly contentType: string;
+	readonly bytes: number;
+	readonly checksum: string;
+	readonly scan: StorageScanVerdict;
+	readonly createdAt: string;
+}
+
+function sealFrame(
 	keyring: Keyring,
 	key: string,
 	plaintext: Uint8Array,
-	metadata: {
-		readonly contentType: string;
-		readonly scan: StorageScanVerdict;
-		readonly createdAt: Date;
-	},
+	draft: FrameDraft,
 ): { readonly frame: Uint8Array; readonly object: StoredObject } {
-	const draft = {
+	const unsealed = {
 		v: 1,
 		keyId: keyring.keyId,
 		iv: '',
 		tag: '',
-		contentType: metadata.contentType,
-		bytes: plaintext.byteLength,
-		checksum: storageChecksum(plaintext),
-		scan: metadata.scan,
-		createdAt: metadata.createdAt.toISOString(),
+		...draft,
 	} satisfies FrameHeader;
-	const sealed = keyring.seal(plaintext, additionalData(key, draft));
+	const sealed = keyring.seal(plaintext, additionalData(key, unsealed));
 	const header: FrameHeader = {
-		...draft,
+		...unsealed,
 		keyId: sealed.keyId,
 		iv: sealed.iv.toString('base64'),
 		tag: sealed.tag.toString('base64'),
@@ -162,19 +162,30 @@ export function encodeStoredObject(
 	};
 }
 
-/** Metadata only. The bytes are authenticated by `openStoredObject`, not here. */
-export function readStoredObjectHeader(
+export function encodeStoredObject(
+	keyring: Keyring,
 	key: string,
-	frame: Uint8Array,
-): StoredObject {
-	return describe(key, parseHeader(frame).header);
+	plaintext: Uint8Array,
+	metadata: {
+		readonly contentType: string;
+		readonly scan: StorageScanVerdict;
+		readonly createdAt: Date;
+	},
+): { readonly frame: Uint8Array; readonly object: StoredObject } {
+	return sealFrame(keyring, key, plaintext, {
+		contentType: metadata.contentType,
+		bytes: plaintext.byteLength,
+		checksum: storageChecksum(plaintext),
+		scan: metadata.scan,
+		createdAt: metadata.createdAt.toISOString(),
+	});
 }
 
-export function openStoredObject(
+function openFrame(
 	keyring: Keyring,
 	key: string,
 	frame: Uint8Array,
-): { readonly object: StoredObject; readonly plaintext: Buffer } {
+): { readonly header: FrameHeader; readonly plaintext: Buffer } {
 	const { header, ciphertextOffset } = parseHeader(frame);
 	const plaintext = keyring.open(
 		{
@@ -185,5 +196,43 @@ export function openStoredObject(
 		},
 		additionalData(key, header),
 	);
+	return { header, plaintext };
+}
+
+/** Metadata only. The bytes are authenticated by `openStoredObject`, not here. */
+export function readStoredObjectHeader(
+	key: string,
+	frame: Uint8Array,
+): StoredObject {
+	return describe(key, parseHeader(frame).header);
+}
+
+export function openStoredObject(
+	keyring: Keyring,
+	key: string,
+	frame: Uint8Array,
+): { readonly object: StoredObject; readonly plaintext: Buffer } {
+	const { header, plaintext } = openFrame(keyring, key, frame);
 	return { object: describe(key, header), plaintext };
 }
+
+/**
+ * The same object under the current key. The frame is opened under the key it
+ * names, which authenticates the header, and the header's own fields become the
+ * additional data of the new frame, so nothing about the object changes but
+ * the key, the nonce, the tag and the ciphertext.
+ */
+export function resealStoredObject(
+	keyring: Keyring,
+	key: string,
+	frame: Uint8Array,
+): { readonly frame: Uint8Array; readonly object: StoredObject } {
+	const { header, plaintext } = openFrame(keyring, key, frame);
+	return sealFrame(keyring, key, plaintext, {
+		contentType: header.contentType,
+		bytes: header.bytes,
+		checksum: header.checksum,
+		scan: header.scan,
+		createdAt: header.createdAt,
+	});
+}

package/packages/storage/src/index.ts

@@ -31,7 +31,13 @@ export { createLocalObjectStore } from './local.ts';
 export { createS3ObjectStore } from './s3.ts';
 export type { S3ObjectStoreOptions } from './s3.ts';
 export { createStoragePort } from './port.ts';
-export type { StoragePortOptions } from './port.ts';
+export type { ManagedStoragePort, StoragePortOptions } from './port.ts';
+export type {
+	StorageResealCount,
+	StorageResealOptions,
+	StorageResealPort,
+	StorageResealReport,
+} from './reseal.ts';
 export {
 	mintStorageReadToken,
 	openStorageReadToken,

package/packages/storage/src/port.ts

@@ -24,6 +24,7 @@ import {
 import { createLocalObjectStore } from './local.ts';
 import { createS3ObjectStore } from './s3.ts';
 import { mintStorageReadToken, storageReadUrl } from './read-token.ts';
+import { createStorageResealer, type StorageResealPort } from './reseal.ts';
 import { unscannedStorageScanner, type StorageScanner } from './scanner.ts';
 import type { StorageConfig } from './config.ts';
 import type { ObjectStore } from './store.ts';
@@ -125,6 +126,9 @@ function objectStoreFor(
 	});
 }
 
+/** The port a deployment builds: the module contract plus the operator pass. */
+export interface ManagedStoragePort extends StoragePort, StorageResealPort {}
+
 /**
  * The one place the storage rules live: the tenant-first key layout, the size
  * limit, the content type allowlist with magic byte verification, the scanner
@@ -133,11 +137,12 @@ function objectStoreFor(
 export function createStoragePort(
 	config: StorageConfig,
 	options: StoragePortOptions,
-): StoragePort {
+): ManagedStoragePort {
 	const store = objectStoreFor(config, options);
 	const scanner = options.scanner ?? unscannedStorageScanner;
 	const clock = options.clock ?? (() => new Date());
 	const keyring = options.keyring;
+	const resealer = createStorageResealer(store, keyring);
 	let disposed = false;
 
 	const live = (): void => {
@@ -242,6 +247,12 @@ export function createStoragePort(
 			return prefix ? readStoredObjectHeader(key, prefix) : null;
 		},
 
+		keyId: keyring.keyId,
+		reseal(objects, options) {
+			live();
+			return resealer.reseal(objects, options);
+		},
+
 		async dispose(): Promise<void> {
 			if (disposed) return;
 			disposed = true;

package/packages/storage/src/reseal.ts

@@ -0,0 +1,128 @@
+import { KeyringError, type Keyring } from '@flowdular/sdk/kernel';
+import {
+	StorageError,
+	storageObjectKey,
+	type StorageObjectRef,
+} from './contracts.ts';
+import {
+	readStoredObjectHeader,
+	resealStoredObject,
+	STORAGE_HEADER_PREFIX_BYTES,
+} from './envelope.ts';
+import type { ObjectStore } from './store.ts';
+
+export interface StorageResealCount {
+	readonly keyId: string;
+	readonly objects: number;
+}
+
+export interface StorageResealReport {
+	/** Key id every object should end on: the current key of the ring. */
+	readonly currentKeyId: string;
+	readonly counts: readonly StorageResealCount[];
+	/** Objects on a retired key the ring still holds. */
+	readonly stale: number;
+	readonly resealed: number;
+	/** Objects sealed under a key id this ring does not hold; left as they are. */
+	readonly unknown: number;
+	/** Objects that failed authentication under the key they name; left as they are. */
+	readonly refused: number;
+	/** References with no object behind them. */
+	readonly missing: number;
+}
+
+export interface StorageResealOptions {
+	readonly apply: boolean;
+}
+
+export interface StorageResealPort {
+	/** Key id every re-seal writes: the current key of the ring. */
+	readonly keyId: string;
+	/**
+	 * Re-seals every object of the batch that a retired key sealed, in place.
+	 * The caller owns the inventory: an adapter cannot list, so the references
+	 * come from the rows that name the objects. Without `apply` the headers are
+	 * read and counted and nothing is written.
+	 */
+	reseal(
+		objects: readonly StorageObjectRef[],
+		options: StorageResealOptions,
+	): Promise<StorageResealReport>;
+}
+
+/* A frame the port cannot parse is left exactly as the one it cannot open:
+   the pass counts it and moves on, and the operator restores it. */
+function corrupt(error: unknown): boolean {
+	return error instanceof StorageError && error.code === 'OBJECT_CORRUPT';
+}
+
+export function createStorageResealer(
+	store: ObjectStore,
+	keyring: Keyring,
+): StorageResealPort {
+	return {
+		keyId: keyring.keyId,
+		async reseal(objects, options) {
+			const counts = new Map<string, number>();
+			let stale = 0;
+			let resealed = 0;
+			let unknown = 0;
+			let refused = 0;
+			let missing = 0;
+			for (const reference of objects) {
+				const key = storageObjectKey(reference);
+				const prefix = await store.read(key, STORAGE_HEADER_PREFIX_BYTES);
+				if (!prefix) {
+					missing += 1;
+					continue;
+				}
+				let keyId: string;
+				try {
+					keyId = readStoredObjectHeader(key, prefix).keyId;
+				} catch (error) {
+					if (corrupt(error)) {
+						refused += 1;
+						continue;
+					}
+					throw error;
+				}
+				counts.set(keyId, (counts.get(keyId) ?? 0) + 1);
+				if (keyId === keyring.keyId) continue;
+				if (!keyring.knows(keyId)) {
+					unknown += 1;
+					continue;
+				}
+				stale += 1;
+				if (!options.apply) continue;
+				const frame = await store.read(key);
+				if (!frame) {
+					missing += 1;
+					continue;
+				}
+				let next;
+				try {
+					next = resealStoredObject(keyring, key, frame);
+				} catch (error) {
+					if (error instanceof KeyringError || corrupt(error)) {
+						refused += 1;
+						continue;
+					}
+					throw error;
+				}
+				await store.write(key, next.frame);
+				resealed += 1;
+			}
+			return {
+				currentKeyId: keyring.keyId,
+				counts: [...counts]
+					.sort(([left], [right]) => (left < right ? -1 : left > right ? 1 : 0))
+					.map(([keyId, count]) => ({ keyId, objects: count })),
+				stale,
+				resealed,
+				unknown,
+				refused,
+				missing,
+			};
+		},
+	};
+}