@drhomet/mithaq 0.0.0-stage → 0.2.0

package/dist/storage/storage.d.ts

@@ -0,0 +1,386 @@
+import { type Command, type Language, type Store } from '../mithaq/language.ts';
+import type { ResolvedKayan } from '../mithaq/types.ts';
+import { type Ctx } from '../asas/runner/steps.ts';
+import type { Authorize, ManagedAdmin } from '../asas/runner/write.ts';
+import type { StandardSchemaV1 } from '../mithaq/standard-schema.ts';
+import { allowedType } from './allowed-type.ts';
+/**
+ * The file columns a kayan that holds files spreads into its fields beside `defaultFields`.
+ * Filled from the verified upload and never changed: a file is replaced by a new row.
+ */
+export declare const uploadFields: {
+    readonly filename: {
+        readonly kind: 'text';
+        readonly label: {
+            readonly en: 'File name';
+            readonly ar: 'اسم الملف';
+        };
+        readonly rules: {
+            readonly providedBy: {
+                readonly create: 'application';
+                readonly update: 'never';
+            };
+            readonly required: true;
+            readonly index: true;
+        };
+    };
+    readonly mimeType: {
+        readonly kind: 'text';
+        readonly label: {
+            readonly en: 'File type';
+            readonly ar: 'نوع الملف';
+        };
+        readonly rules: {
+            readonly providedBy: {
+                readonly create: 'application';
+                readonly update: 'never';
+            };
+            readonly required: true;
+        };
+    };
+    readonly filesize: {
+        readonly kind: 'number';
+        readonly label: {
+            readonly en: 'File size';
+            readonly ar: 'حجم الملف';
+        };
+        readonly rules: {
+            readonly providedBy: {
+                readonly create: 'application';
+                readonly update: 'never';
+            };
+            readonly required: true;
+        };
+    };
+    readonly width: {
+        readonly kind: 'number';
+        readonly label: {
+            readonly en: 'Width';
+            readonly ar: 'العرض';
+        };
+        readonly rules: {
+            readonly providedBy: {
+                readonly create: 'application';
+                readonly update: 'never';
+            };
+        };
+    };
+    readonly height: {
+        readonly kind: 'number';
+        readonly label: {
+            readonly en: 'Height';
+            readonly ar: 'الارتفاع';
+        };
+        readonly rules: {
+            readonly providedBy: {
+                readonly create: 'application';
+                readonly update: 'never';
+            };
+        };
+    };
+    readonly key: {
+        readonly kind: 'text';
+        readonly label: {
+            readonly en: 'Object key';
+            readonly ar: 'مفتاح الملف';
+        };
+        readonly rules: {
+            readonly providedBy: {
+                readonly create: 'application';
+                readonly update: 'never';
+            };
+            readonly required: true;
+            readonly unique: true;
+        };
+    };
+    readonly storage: {
+        readonly kind: 'text';
+        readonly label: {
+            readonly en: 'Storage';
+            readonly ar: 'التخزين';
+        };
+        readonly rules: {
+            readonly providedBy: {
+                readonly create: 'application';
+                readonly update: 'never';
+            };
+            readonly required: true;
+        };
+    };
+};
+/** The storage target as the language holds it: a capability, the project's config, and the `sweep` command. */
+export type StorageTarget = {
+    readonly capability: 'storage';
+    readonly type: 'storage';
+    readonly config: StorageConfig;
+    readonly commands: {
+        readonly sweep: Command;
+    };
+};
+/** What a kayan writes under the storage target: the types it holds, its largest file in bytes, and whether its `url` is public. */
+export type KayanStorage = {
+    readonly mimeTypes: readonly string[];
+    readonly fileSize?: number;
+    readonly public?: true;
+};
+/** The request the browser sends the file with. */
+export type UploadRequest = {
+    type: 'http';
+    request: {
+        method: 'PUT' | 'POST';
+        url: string;
+        headers?: Record<string, string>;
+    };
+};
+/** What the browser sends the file with, and the signed reference the create takes back. */
+export type UploadInstructions = UploadRequest & {
+    file: {
+        filename: string;
+        mimeType: string;
+        size: number;
+        uploadReference: UploadReference;
+    };
+};
+/** A row of a storage kayan, as much of it as an adapter reads. */
+export type StoredFile = {
+    id: unknown;
+    key: string;
+    filename: string;
+    mimeType: string;
+    filesize: number;
+    storage: string;
+};
+/** One place files are kept. */
+export type StorageAdapter = {
+    /** The folder of the store this adapter owns; `list` reads it alone, so a sweep of a shared bucket touches no other app's objects. */
+    prefix: string;
+    uploadInstructions: {
+        generate(args: {
+            filename: string;
+            filesize: number;
+            mimeType: string;
+            key: string;
+        }): Promise<UploadRequest>;
+    };
+    handleDelete(args: {
+        key: string;
+    }): Promise<void>;
+    /** The public address of an object, for a kayan that writes `public: true`. */
+    generateURL?(args: {
+        key: string;
+    }): string;
+    /** A 302 to a short-lived signed address, or the bytes themselves. */
+    staticHandler(request: Request, args: {
+        doc: StoredFile;
+        disposition: string;
+    }): Promise<Response>;
+    /** The stored object's size, or null where there is none. */
+    head(args: {
+        key: string;
+    }): Promise<{
+        size: number;
+    } | null>;
+    /** The first `bytes` of the stored object. */
+    readHead(args: {
+        key: string;
+        bytes: number;
+    }): Promise<Uint8Array>;
+    /** Every object this adapter holds, with when it was last written. */
+    list?(): AsyncIterable<{
+        key: string;
+        lastModified: Date;
+    }>;
+    handler?(request: Request): Promise<Response | null>;
+};
+/** What a verification reads, and what it answers: the image's size, or why the file is refused. */
+export type VerifyArgs = {
+    adapter: StorageAdapter;
+    key: string;
+    mimeType: string;
+    size: number;
+    mimeTypes: readonly string[];
+    fileSize: number;
+};
+export type Verified = {
+    width?: number | null;
+    height?: number | null;
+} | {
+    refused: string;
+};
+/** What a sweep is handed, per adapter, and the keys it found no row naming. */
+export type SweepArgs = {
+    adapter: StorageAdapter;
+    named: ReadonlySet<string>;
+    check: boolean;
+    now: Date;
+};
+/** A step of the storage flow, `(ctx, tools)` as every step is. */
+export type StorageStep = (ctx: Ctx, tools?: unknown) => Promise<Ctx>;
+/** What the storage rukn takes, `storage(storageConfig)`. Every key is required. */
+export type StorageConfig = {
+    /** The key upload references are signed with, 32 characters at least. */
+    secret: string;
+    /** Every adapter by the name a row's `storage` column holds. */
+    adapters: Readonly<Record<string, StorageAdapter>>;
+    /** The adapter a new upload goes to. */
+    adapter: string;
+    /** The largest file in bytes a kayan holds when its `targets.storage` names no `fileSize`. */
+    fileSize: number;
+    /** The largest request body `uploadInstructions` reads, answered 413 past it: `defaultMaxBodyBytes` or the project's own. */
+    maxBodyBytes: number;
+    /** The object key, decided before the upload. */
+    key: (args: {
+        prefix: string;
+        tenant: string | null;
+        kayan: string;
+        id: string;
+        filename: string;
+    }) => string;
+    verify: (args: VerifyArgs) => Promise<Verified>;
+    disposition: (args: {
+        filename: string;
+        mimeType: string;
+    }) => string;
+    sweep: (args: SweepArgs) => Promise<string[]>;
+    /** `POST /api/<kayan>/uploadInstructions`, asked once the actor holds the operation that makes the kayan's rows. */
+    instructions: (args: {
+        kayan: StorageKayan;
+        input: unknown;
+        actor: unknown;
+    }) => Promise<UploadInstructions>;
+    /** The `beforeTransaction` step of the operation that makes a row: the reference checked, the object verified, the file columns written. */
+    uploaded: StorageStep;
+    /** The delete's `afterCommit` step, removing the deleted row's object. */
+    removed: StorageStep;
+    /** `GET /api/<kayan>/file/<id>`: `read` is the kayan's own `findByID`, as the actor. */
+    serve: (args: {
+        request: Request;
+        kayan: StorageKayan;
+        id: string;
+        read: (args: {
+            id: string;
+        }) => Promise<Record<string, unknown> | null>;
+    }) => Promise<Response>;
+    /** Handed what a file route threw that is no refusal, before it answers 500 with the message replaced. */
+    onError: (error: unknown) => void;
+};
+export type ResolvedStorage = {
+    mimeTypes: readonly string[];
+    fileSize: number;
+    public: boolean;
+    config: StorageConfig;
+    operation: string;
+    exists: (id: string) => Promise<boolean>;
+    /** The organization this actor's files of the kayan are kept under: null for a shared kayan, nothing where a tenant-owned one has no active organization. */
+    tenant: (actor: unknown) => string | null | undefined;
+};
+/** A kayan that holds files, as `buildAsas` hands it to the storage functions. */
+export type StorageKayan = ResolvedKayan & {
+    storage: ResolvedStorage;
+};
+/** The signed reference an upload's create hands back: what the server decided, and its signature. */
+export type UploadReference = {
+    id: string;
+    key: string;
+    kayan: string;
+    tenant: string | null;
+    filename: string;
+    type: string;
+    size: number;
+    storage: string;
+    exp: number;
+    signature: string;
+};
+/** The `fileSize` the template names in its storage config: 10 MiB. */
+export declare const defaultFileSize: number;
+/** The type check both halves make, in a module the browser imports too. */
+export { allowedType };
+/** The file name with every directory part and control character dropped, or an empty string. */
+export declare const sanitizeFilename: (filename: string) => string;
+/** The adapter a row or a reference names. Read as an own key, so no name reaches an inherited property. */
+export declare const adapterOf: ({ kayan, name }: {
+    kayan: ResolvedKayan;
+    name: unknown;
+}) => StorageAdapter;
+/**
+ * Signs the reference an upload's create must name back: the row's id, the key, the kayan,
+ * the actor's tenant from its session, the file, the adapter and an expiry, under HMAC-SHA256.
+ */
+export declare const signReference: ({ kayan, actor, id, filename, type, size, }: {
+    kayan: ResolvedKayan;
+    actor: unknown;
+    id: string;
+    filename: string;
+    type: string;
+    size: number;
+}) => UploadReference;
+/**
+ * Checks the reference a create names back, refusing every way it can be wrong in one
+ * sentence so a forged one reads as an expired one. The signature is compared in constant time.
+ */
+export declare const checkReference: ({ kayan, value, actor }: {
+    kayan: ResolvedKayan;
+    value: unknown;
+    actor: unknown;
+}) => Promise<UploadReference>;
+/** The create shape of a kayan holding files, with the `uploadReference` beside it. */
+export declare const withUploadReference: (create: StandardSchemaV1) => StandardSchemaV1;
+export declare const resolveStorage: ({ language, resolved, storeOf, active }: {
+    language: Language;
+    resolved: ResolvedKayan[];
+    storeOf: Swept['storeOf'];
+    /** The organization the actor's verified session has active, the one a tenant-owned kayan's files are kept under. */
+    active: (actor: unknown) => string | undefined;
+}) => StorageKayan[];
+/** A row's `url` and `thumbnailURL`, computed on read: the file route, or the adapter's public address. */
+export declare const fileURLs: ({ kayan, stored, visible, }: {
+    kayan: ResolvedKayan;
+    stored: Record<string, unknown>;
+    visible: Record<string, unknown>;
+}) => Record<string, unknown>;
+/**
+ * The row a file route serves, read through the kayan's own `findByID` as the actor. Every
+ * reason it cannot be served is the same 404, so no answer tells one from another.
+ */
+export declare const readForFile: ({ kayan, id, read }: {
+    kayan: ResolvedKayan;
+    id: string;
+    read: (args: {
+        id: string;
+    }) => Promise<Record<string, unknown> | null>;
+}) => Promise<StoredFile>;
+/**
+ * Serves a file under the headers its bytes need. An SVG is never `inline` and
+ * gets a policy that runs no script.
+ */
+export declare const fileHeaders: ({ doc, disposition, answer, }: {
+    doc: StoredFile;
+    disposition: string;
+    answer: (args: {
+        disposition: string;
+    }) => Promise<Response>;
+}) => Promise<Response>;
+export declare const storageRoutes: <Actor>({ kayan, config, read, authorize, admin, }: {
+    kayan: readonly StorageKayan[];
+    config: StorageConfig;
+    read: (args: {
+        kayan: string;
+        id: string;
+        actor: Actor | null;
+    }) => Promise<Record<string, unknown> | null>;
+    authorize: Authorize;
+    admin?: ManagedAdmin<Actor>;
+}) => (request: Request, who: () => Promise<Actor | null>) => Promise<Response | null>;
+type Swept = {
+    config: StorageConfig;
+    kayan: readonly ResolvedKayan[];
+    storeOf: (kayan: ResolvedKayan) => Store;
+};
+export declare const recordStorage: (asas: object, swept: Swept) => undefined;
+/** The storage target over the project's config. The storage rukn builds it. */
+export declare const storageTarget: (config: StorageConfig) => StorageTarget;
+declare module '../mithaq/rukn.ts' {
+    interface KayanConfigs<L, F, T> {
+        storage: KayanStorage;
+    }
+}