@flowdular/sdk 0.2.3 → 0.3.0

package/packages/storage/src/read-token.ts

@@ -0,0 +1,130 @@
+import { KeyringError, type Keyring } from '@flowdular/sdk/kernel';
+import {
+	StorageError,
+	STORAGE_READ_ROUTE_PREFIX,
+	STORAGE_READ_URL_MAX_SECONDS,
+	type StorageObjectRef,
+} from './contracts.ts';
+
+/* The read token is the capability: it names the object, carries its own
+   expiry, and needs no session. It is sealed rather than signed, so the tenant
+   id never travels in a URL a proxy or a browser history would keep, and the
+   GCM tag is what makes a forged token impossible rather than merely unlikely.
+
+     version(1) | keyId(16 ascii) | iv(12) | tag(16) | ciphertext
+
+   The additional data is a constant unique to this use, so an object envelope
+   can never be replayed as a token and vice versa. */
+
+const TOKEN_VERSION = 1;
+const KEY_ID_BYTES = 16;
+const IV_BYTES = 12;
+const TAG_BYTES = 16;
+const HEADER_BYTES = 1 + KEY_ID_BYTES + IV_BYTES + TAG_BYTES;
+const TOKEN_AAD = 'flowdular-storage-read-token:v1';
+/* A payload is a fixed handful of ids; anything longer is not one, and parsing
+   stops before the decode rather than after it. */
+const TOKEN_CHARACTER_LIMIT = 1024;
+
+interface TokenPayload {
+	readonly t: string;
+	readonly m: string;
+	readonly o: string;
+	readonly e: number;
+}
+
+export interface StorageReadToken extends StorageObjectRef {
+	readonly expiresAt: Date;
+}
+
+export function mintStorageReadToken(
+	keyring: Keyring,
+	input: StorageObjectRef & {
+		readonly expiresInSeconds: number;
+		readonly now: Date;
+	},
+): string {
+	if (
+		!Number.isInteger(input.expiresInSeconds) ||
+		input.expiresInSeconds < 1 ||
+		input.expiresInSeconds > STORAGE_READ_URL_MAX_SECONDS
+	) {
+		throw new StorageError(
+			'EXPIRY_INVALID',
+			`A read URL expires in 1 to ${STORAGE_READ_URL_MAX_SECONDS} seconds.`,
+		);
+	}
+	const payload: TokenPayload = {
+		t: input.tenantId,
+		m: input.moduleId,
+		o: input.objectId,
+		e:
+			Math.floor(input.now.getTime() / 1000) +
+			Math.trunc(input.expiresInSeconds),
+	};
+	const sealed = keyring.seal(JSON.stringify(payload), TOKEN_AAD);
+	const keyId = Buffer.from(sealed.keyId.padEnd(KEY_ID_BYTES, '0'), 'latin1');
+	return Buffer.concat([
+		Buffer.of(TOKEN_VERSION),
+		keyId.subarray(0, KEY_ID_BYTES),
+		sealed.iv,
+		sealed.tag,
+		sealed.ciphertext,
+	]).toString('base64url');
+}
+
+/**
+ * The token's object reference, or null for anything a caller must not be able
+ * to tell apart: a malformed token, a key this ring does not hold, a forged tag
+ * and an expired capability all answer the same way.
+ */
+export function openStorageReadToken(
+	keyring: Keyring,
+	token: string,
+	now: Date,
+): StorageReadToken | null {
+	if (token.length === 0 || token.length > TOKEN_CHARACTER_LIMIT) return null;
+	const raw = Buffer.from(token, 'base64url');
+	if (raw.byteLength <= HEADER_BYTES || raw[0] !== TOKEN_VERSION) return null;
+	let opened: Buffer;
+	try {
+		opened = keyring.open(
+			{
+				keyId: raw.subarray(1, 1 + KEY_ID_BYTES).toString('latin1'),
+				iv: raw.subarray(1 + KEY_ID_BYTES, 1 + KEY_ID_BYTES + IV_BYTES),
+				tag: raw.subarray(1 + KEY_ID_BYTES + IV_BYTES, HEADER_BYTES),
+				ciphertext: raw.subarray(HEADER_BYTES),
+			},
+			TOKEN_AAD,
+		);
+	} catch (error) {
+		if (error instanceof KeyringError) return null;
+		throw error;
+	}
+	let payload: TokenPayload;
+	try {
+		payload = JSON.parse(opened.toString('utf8')) as TokenPayload;
+	} catch {
+		return null;
+	}
+	if (
+		typeof payload.t !== 'string' ||
+		typeof payload.m !== 'string' ||
+		typeof payload.o !== 'string' ||
+		!Number.isSafeInteger(payload.e)
+	) {
+		return null;
+	}
+	const expiresAt = new Date(payload.e * 1000);
+	if (expiresAt.getTime() <= now.getTime()) return null;
+	return {
+		tenantId: payload.t,
+		moduleId: payload.m,
+		objectId: payload.o,
+		expiresAt,
+	};
+}
+
+export function storageReadUrl(token: string): string {
+	return `${STORAGE_READ_ROUTE_PREFIX}${token}`;
+}

package/packages/storage/src/s3.ts

@@ -0,0 +1,144 @@
+import { StorageError } from './contracts.ts';
+import {
+	encodeS3Path,
+	sha256Hex,
+	signS3Request,
+	type SigV4Credentials,
+} from './sigv4.ts';
+import type { ObjectStore } from './store.ts';
+
+const REQUEST_TIMEOUT_MS = 30_000;
+/* An S3 error body is XML naming a code and the resource. Only the code reaches
+   the message, bounded, so a provider cannot grow an exception text at will. */
+const ERROR_CODE_LIMIT = 64;
+
+export interface S3ObjectStoreOptions {
+	readonly bucket: string;
+	readonly region: string;
+	/** Absent uses the AWS endpoint for the region; MinIO and R2 set their own. */
+	readonly endpoint?: string | undefined;
+	readonly accessKeyId: string;
+	readonly secretAccessKey: string;
+	/** MinIO and most self-hosted gateways need `<endpoint>/<bucket>/<key>`. */
+	readonly forcePathStyle: boolean;
+	readonly fetch?: typeof globalThis.fetch | undefined;
+	readonly clock?: (() => Date) | undefined;
+}
+
+function errorCode(body: string): string {
+	return (
+		/<Code>([^<]{1,64})<\/Code>/.exec(body)?.[1]?.slice(0, ERROR_CODE_LIMIT) ??
+		'unknown'
+	);
+}
+
+async function unavailable(
+	action: string,
+	response: Response,
+): Promise<StorageError> {
+	const body = await response.text().catch(() => '');
+	return new StorageError(
+		'STORAGE_UNAVAILABLE',
+		`The object store refused to ${action}: HTTP ${response.status} ${errorCode(body)}.`,
+	);
+}
+
+export function createS3ObjectStore(
+	options: S3ObjectStoreOptions,
+): ObjectStore {
+	const credentials: SigV4Credentials = {
+		accessKeyId: options.accessKeyId,
+		secretAccessKey: options.secretAccessKey,
+		region: options.region,
+	};
+	const call = options.fetch ?? globalThis.fetch;
+	const clock = options.clock ?? (() => new Date());
+	const endpoint = new URL(
+		options.endpoint?.trim() || `https://s3.${options.region}.amazonaws.com`,
+	);
+	const origin = options.forcePathStyle
+		? `${endpoint.protocol}//${endpoint.host}`
+		: `${endpoint.protocol}//${options.bucket}.${endpoint.host}`;
+	const host = new URL(origin).host;
+	const basePath = options.forcePathStyle ? `/${options.bucket}` : '';
+
+	async function request(
+		method: string,
+		key: string,
+		init: {
+			readonly body?: Uint8Array | undefined;
+			readonly headers?: Readonly<Record<string, string>> | undefined;
+		} = {},
+	): Promise<Response> {
+		const canonicalUri = encodeS3Path(`${basePath}/${key}`);
+		const signed = signS3Request({
+			method,
+			canonicalUri,
+			headers: { host, ...init.headers },
+			payloadHash: sha256Hex(init.body ?? ''),
+			credentials,
+			now: clock(),
+		});
+		/* fetch owns Host and sets it from the URL, so sending the signed copy is
+		   both refused and unnecessary: the value the server reads is the one the
+		   signature covers. Content-Length is forbidden for the same reason, which
+		   is why it is neither sent nor signed. */
+		const { host: _signedHost, ...sendable } = signed;
+		try {
+			return await call(`${origin}${canonicalUri}`, {
+				method,
+				headers: sendable,
+				/* fetch accepts a typed array body at run time; BodyInit only spells
+				   the ArrayBuffer-backed view, and copying the frame to satisfy the
+				   type would double what one request holds. */
+				...(init.body ? { body: init.body as unknown as BodyInit } : {}),
+				signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+			});
+		} catch (error) {
+			throw new StorageError(
+				'STORAGE_UNAVAILABLE',
+				`The object store did not answer a ${method} request.`,
+				{ cause: error },
+			);
+		}
+	}
+
+	return {
+		async write(key, frame) {
+			const response = await request('PUT', key, {
+				body: frame,
+				headers: { 'content-type': 'application/octet-stream' },
+			});
+			if (!response.ok) throw await unavailable(`store ${key}`, response);
+			await response.body?.cancel();
+		},
+		async read(key, maxBytes) {
+			const response = await request('GET', key, {
+				...(maxBytes === undefined
+					? {}
+					: { headers: { range: `bytes=0-${maxBytes - 1}` } }),
+			});
+			if (response.status === 404) {
+				await response.body?.cancel();
+				return null;
+			}
+			if (!response.ok) throw await unavailable(`read ${key}`, response);
+			return new Uint8Array(await response.arrayBuffer());
+		},
+		async remove(key) {
+			/* S3 deletes are idempotent and answer 204 for an absent key, so the
+			   caller is told whether the object was there by looking first. */
+			const head = await request('HEAD', key);
+			await head.body?.cancel();
+			if (head.status === 404) return false;
+			if (!head.ok) throw await unavailable(`read ${key}`, head);
+			const response = await request('DELETE', key);
+			if (!response.ok && response.status !== 404) {
+				throw await unavailable(`delete ${key}`, response);
+			}
+			await response.body?.cancel();
+			return true;
+		},
+		close: () => Promise.resolve(),
+	};
+}

package/packages/storage/src/scanner.ts

@@ -0,0 +1,22 @@
+import type { StorageScanVerdict } from './contracts.ts';
+
+export interface StorageScanResult {
+	readonly verdict: StorageScanVerdict;
+}
+
+/**
+ * The seam a deployment fills with a malware scanner. It reads the plaintext
+ * stream and answers with a verdict; the platform refuses `infected` and stores
+ * the verdict with the object so a later policy change can find what was never
+ * scanned.
+ */
+export interface StorageScanner {
+	scan(
+		body: ReadableStream<Uint8Array>,
+	): StorageScanResult | Promise<StorageScanResult>;
+}
+
+/** No scanner configured. Every object is stored with the `unscanned` verdict. */
+export const unscannedStorageScanner: StorageScanner = Object.freeze({
+	scan: () => ({ verdict: 'unscanned' as const }),
+});

package/packages/storage/src/sigv4.ts

@@ -0,0 +1,104 @@
+import { createHash, createHmac } from 'node:crypto';
+
+/* AWS Signature Version 4 for the four S3 operations the port performs. The
+   whole surface is PutObject, GetObject (whole and ranged) and DeleteObject, so
+   the signer is a hundred lines of node:crypto rather than an SDK and its
+   transitive tree in every generated application. */
+
+const ALGORITHM = 'AWS4-HMAC-SHA256';
+const SERVICE = 's3';
+
+export interface SigV4Credentials {
+	readonly accessKeyId: string;
+	readonly secretAccessKey: string;
+	readonly region: string;
+}
+
+export function sha256Hex(value: Uint8Array | string): string {
+	return createHash('sha256').update(value).digest('hex');
+}
+
+function hmac(key: Uint8Array | string, value: string): Buffer {
+	return createHmac('sha256', key).update(value, 'utf8').digest();
+}
+
+/**
+ * RFC 3986 encoding per path segment, with `/` kept as the separator. S3 signs
+ * the object key exactly as it appears in the request line, so the same
+ * function produces the path and the canonical URI.
+ */
+export function encodeS3Path(path: string): string {
+	return path
+		.split('/')
+		.map((segment) =>
+			encodeURIComponent(segment).replace(
+				/[!'()*]/g,
+				(character) => `%${character.charCodeAt(0).toString(16).toUpperCase()}`,
+			),
+		)
+		.join('/');
+}
+
+/** `YYYYMMDDTHHMMSSZ`, the only timestamp spelling SigV4 accepts. */
+export function amazonDate(now: Date): string {
+	return `${now.toISOString().replace(/[-:]/g, '').split('.')[0]}Z`;
+}
+
+/**
+ * The request headers plus `x-amz-date`, `x-amz-content-sha256` and
+ * `authorization`. `canonicalUri` is the already-encoded path, so nothing is
+ * encoded twice.
+ */
+export function signS3Request(input: {
+	readonly method: string;
+	readonly canonicalUri: string;
+	readonly headers: Readonly<Record<string, string>>;
+	readonly payloadHash: string;
+	readonly credentials: SigV4Credentials;
+	readonly now: Date;
+}): Record<string, string> {
+	const timestamp = amazonDate(input.now);
+	const date = timestamp.slice(0, 8);
+	const headers: Record<string, string> = {
+		...input.headers,
+		'x-amz-content-sha256': input.payloadHash,
+		'x-amz-date': timestamp,
+	};
+	const canonical = new Map<string, string>();
+	for (const [name, value] of Object.entries(headers)) {
+		canonical.set(name.toLowerCase(), value.trim().replace(/\s+/g, ' '));
+	}
+	const names = [...canonical.keys()].sort();
+	const canonicalHeaders = names
+		.map((name) => `${name}:${canonical.get(name) ?? ''}\n`)
+		.join('');
+	const signedHeaders = names.join(';');
+	const canonicalRequest = [
+		input.method,
+		input.canonicalUri,
+		'',
+		canonicalHeaders,
+		signedHeaders,
+		input.payloadHash,
+	].join('\n');
+	const scope = `${date}/${input.credentials.region}/${SERVICE}/aws4_request`;
+	const stringToSign = [
+		ALGORITHM,
+		timestamp,
+		scope,
+		sha256Hex(canonicalRequest),
+	].join('\n');
+	const signingKey = hmac(
+		hmac(
+			hmac(
+				hmac(`AWS4${input.credentials.secretAccessKey}`, date),
+				input.credentials.region,
+			),
+			SERVICE,
+		),
+		'aws4_request',
+	);
+	const signature = hmac(signingKey, stringToSign).toString('hex');
+	headers.authorization = `${ALGORITHM} Credential=${input.credentials.accessKeyId}/${scope}, SignedHeaders=${signedHeaders}, Signature=${signature}`;
+	return headers;
+}

package/packages/storage/src/store.ts

@@ -0,0 +1,13 @@
+/**
+ * What an adapter does, and all it does: move opaque frames. Validation, the
+ * key layout, encryption, scanning and read tokens live in one place above it,
+ * so a second adapter cannot weaken a rule by forgetting it.
+ */
+export interface ObjectStore {
+	write(key: string, frame: Uint8Array): Promise<void>;
+	/** `maxBytes` reads only the frame prefix, for a metadata-only read. */
+	read(key: string, maxBytes?: number): Promise<Uint8Array | null>;
+	/** False when the object was already absent, so deletion is idempotent. */
+	remove(key: string): Promise<boolean>;
+	close(): Promise<void>;
+}

package/packages/ui/package.json

@@ -20,6 +20,7 @@
 	},
 	"devDependencies": {
 		"@tsrx/typescript-plugin": "0.3.120",
+		"jsdom": "30.0.1",
 		"typescript": "5.9.3",
 		"vitest": "4.1.11"
 	},

package/packages/ui/src/components/Button.tsrx

@@ -9,6 +9,8 @@ export interface ButtonProps {
 	type?: 'button' | 'submit';
 	block?: boolean;
 	disabled?: boolean;
+	/** Id of the element describing the button, e.g. why this one is disabled. */
+	describedBy?: string | undefined;
 	onClick?: () => void;
 	children?: OctaneNode;
 }
@@ -24,6 +26,7 @@ export function Button(props: ButtonProps) @{
 		]}
 		type={props.type ?? 'button'}
 		disabled={props.disabled ?? false}
+		aria-describedby={props.describedBy}
 		onClick={() => props.onClick?.()}
 	>{props.children}</button>
 }

package/packages/ui/src/components/ConfirmDialog.tsrx

@@ -1,6 +1,7 @@
-import { useEffect } from 'octane';
+import { useEffect, useRef } from 'octane';
 import type { OctaneNode } from 'octane';
 import { Button } from './Button.tsrx';
+import { trapFocus } from './focus-trap.ts';
 
 export interface ConfirmDialogProps {
 	open: boolean;
@@ -17,13 +18,21 @@ export interface ConfirmDialogProps {
 }
 
 export function ConfirmDialog(props: ConfirmDialogProps) @{
+	const panelRef = useRef<HTMLDivElement | null>(null);
+
 	useEffect(() => {
 		if (!props.open) return;
 		const onKeyDown = (event: KeyboardEvent) => {
 			if (event.key === 'Escape') props.onCancel();
 		};
 		window.addEventListener('keydown', onKeyDown);
-		return () => window.removeEventListener('keydown', onKeyDown);
+		const panel = panelRef.current;
+		const release =
+			panel === null ? undefined : trapFocus(panel);
+		return () => {
+			window.removeEventListener('keydown', onKeyDown);
+			release?.();
+		};
 	}, [props.open]);
 
 	<div class="ui-drawer-slot">
@@ -38,6 +47,8 @@ export function ConfirmDialog(props: ConfirmDialogProps) @{
 					role="alertdialog"
 					aria-modal="true"
 					aria-label={props.title}
+					tabindex={-1}
+					ref={panelRef}
 					onClick={(event: MouseEvent) => event.stopPropagation()}
 				>
 					<b class="ui-dialog__title">{props.title}</b>

package/packages/ui/src/components/DateField.tsrx

@@ -0,0 +1,92 @@
+import { Icon } from '../icons/Icon.tsrx';
+import {
+	dateInputType,
+	formatDateValue,
+	type DateFieldKind,
+} from './date-field.ts';
+
+export interface DateFieldProps {
+	/** Required: the label's target and a stable form control id. */
+	readonly id: string;
+	readonly label: string;
+	/** ISO value: 'YYYY-MM-DD', or 'YYYY-MM-DDTHH:mm' when `kind` is 'datetime'. */
+	readonly value: string;
+	readonly onChange: (value: string) => void;
+	readonly kind?: DateFieldKind | undefined;
+	/** BCP 47 tag for the reading beside the field; screens pass `activeLocale()`. */
+	readonly locale?: string | undefined;
+	/** ISO bounds handed straight to the native input. */
+	readonly min?: string | undefined;
+	readonly max?: string | undefined;
+	/** Submitted field name; defaults to `id`. */
+	readonly name?: string | undefined;
+	readonly required?: boolean | undefined;
+	readonly disabled?: boolean | undefined;
+	readonly invalid?: boolean | undefined;
+	readonly help?: string | undefined;
+	readonly error?: string | undefined;
+	/** Id of a message owned by a group around the field, e.g. a `DateRangeField`. */
+	readonly describedBy?: string | undefined;
+}
+
+/* A fieldset's own aria-describedby does not reach the controls inside it, so a
+   group hands its message id to every field it holds. */
+function describedBy(props: DateFieldProps): string | undefined {
+	const own =
+		props.error
+			? props.id + '-error'
+			: props.help
+				? props.id + '-help'
+				: '';
+	return [own, props.describedBy ?? ''].filter(Boolean).join(' ') || undefined;
+}
+
+/**
+ * The native date and datetime control. The input carries the ISO value the
+ * platform stores and the form submits; the reader gets the same instant
+ * beside it in their own locale, because a native date input shows whatever
+ * format the browser chose.
+ */
+export function DateField(props: DateFieldProps) @{
+	const invalid = props.invalid === true || (props.error ?? '') !== '';
+	const reading = formatDateValue(props.value, props.kind, props.locale);
+	<div class="ui-field">
+		<label class="ui-label" for={props.id}>
+			{props.label}
+			@if (props.required) {
+				<em aria-hidden="true">{' *'}</em>
+			}
+		</label>
+		<div class="ui-datefield">
+			<input
+				class={['ui-input', invalid && 'ui-input--error']}
+				type={dateInputType(props.kind)}
+				id={props.id}
+				name={props.name ?? props.id}
+				value={props.value}
+				min={props.min ?? undefined}
+				max={props.max ?? undefined}
+				required={props.required ?? false}
+				disabled={props.disabled ?? false}
+				aria-invalid={invalid}
+				aria-describedby={describedBy(props)}
+				onInput={(event) => props.onChange(event.currentTarget.value)}
+			/>
+			@if (reading) {
+				<span class="ui-datefield__reading">
+					<Icon name="calendar" size={14} />
+					{reading}
+				</span>
+			}
+		</div>
+		@if (props.error) {
+			<span
+				class="ui-help ui-help--error"
+				id={props.id + '-error'}
+				role="alert"
+			>{props.error}</span>
+		} @else if (props.help) {
+			<span class="ui-help" id={props.id + '-help'}>{props.help}</span>
+		}
+	</div>
+}