@krizaka/storage 0.0.0-stage → 0.3.0

package/dist/index.js

@@ -0,0 +1,161 @@
+import {
+  COUNTRY_OF_REGION,
+  STORE_KIND,
+  countryOf,
+  describeStore,
+  encryptedStore,
+  parseEncryptionKey,
+  parseSecretKey,
+  residencyOf,
+  residencyOfConfig,
+  storageNotice,
+  where
+} from "./chunk-C3LEYKGC.js";
+import {
+  STORAGE_CODE,
+  StorageError,
+  assertKey,
+  bucketStore,
+  checkEndpoint,
+  defineLayout,
+  folderStore,
+  hashOf,
+  hashedName,
+  remoteStore,
+  trimSlashes,
+  typeOfName
+} from "./chunk-W56662PQ.js";
+
+// src/memory-store.ts
+function memoryObjectStore(options = {}) {
+  const files = /* @__PURE__ */ new Map();
+  return {
+    async put(key, bytes, meta) {
+      files.set(assertKey(key), { bytes: new Uint8Array(bytes), contentType: meta.contentType });
+    },
+    async get(key) {
+      const f = files.get(assertKey(key));
+      return f ? { bytes: new Uint8Array(f.bytes), contentType: f.contentType || typeOfName(key) } : null;
+    },
+    async head(key) {
+      const f = files.get(assertKey(key));
+      return f ? { key, size: f.bytes.byteLength } : null;
+    },
+    async delete(key) {
+      files.delete(assertKey(key));
+    },
+    async list(prefix) {
+      return [...files.entries()].filter(([key]) => key.startsWith(prefix)).map(([key, f]) => ({ key, size: f.bytes.byteLength })).sort((a, b) => a.key.localeCompare(b.key));
+    },
+    async signedUrl() {
+      return null;
+    },
+    publicUrl: (key) => options.publicBaseUrl ? `${trimSlashes(options.publicBaseUrl, "end")}/${assertKey(key)}` : null
+  };
+}
+
+// src/sniff.ts
+var startsWith = (bytes, signature, offset = 0) => signature.every((b, i) => bytes[offset + i] === b);
+var ascii = (bytes, from, to) => String.fromCharCode(...bytes.subarray(from, to));
+function sniffType(bytes) {
+  if (startsWith(bytes, [137, 80, 78, 71, 13, 10, 26, 10])) return "image/png";
+  if (startsWith(bytes, [255, 216, 255])) return "image/jpeg";
+  if (ascii(bytes, 0, 4) === "GIF8") return "image/gif";
+  if (ascii(bytes, 0, 4) === "RIFF" && ascii(bytes, 8, 12) === "WEBP") return "image/webp";
+  if (ascii(bytes, 0, 5) === "%PDF-") return "application/pdf";
+  if (ascii(bytes, 4, 8) === "ftyp") return "video/mp4";
+  if (startsWith(bytes, [26, 69, 223, 163])) return "video/webm";
+  const head = new TextDecoder("utf-8", { fatal: false }).decode(bytes.subarray(0, 512)).replace("\uFEFF", "").trimStart();
+  if (startsSvg(head)) return "image/svg+xml";
+  return null;
+}
+function startsSvg(text) {
+  let rest = text;
+  if (rest.startsWith("<?xml")) {
+    const end = rest.indexOf("?>");
+    if (end < 0) return false;
+    rest = rest.slice(end + 2).trimStart();
+  }
+  while (rest.startsWith("<!--")) {
+    const end = rest.indexOf("-->");
+    if (end < 0) return false;
+    rest = rest.slice(end + 3).trimStart();
+  }
+  return /^<svg[\s>]/i.test(rest);
+}
+
+// src/storage.ts
+function createStorage(deps) {
+  const limits = async () => typeof deps.limits === "function" ? await deps.limits() : deps.limits;
+  const urlFor = async (key) => deps.store.publicUrl(key) ?? await deps.store.signedUrl(key, (await limits()).signedUrlSeconds);
+  return {
+    async upload(input) {
+      const { maxBytes } = await limits();
+      if (input.bytes.byteLength === 0 || input.bytes.byteLength > maxBytes) throw new StorageError(STORAGE_CODE.tooBig, `a file is 1 to ${maxBytes} bytes`);
+      const actual = sniffType(input.bytes);
+      if (actual === null || !input.allow.includes(actual)) throw new StorageError(STORAGE_CODE.badType, `the bytes are ${actual ?? "of an unknown type"}, not one of ${input.allow.join(", ")}`);
+      if (input.declaredType !== void 0 && input.declaredType !== actual) throw new StorageError(STORAGE_CODE.typeMismatch, `declared ${input.declaredType}, the bytes are ${actual}`);
+      const key = deps.layout.check(`${input.prefix}${hashedName(input.name, input.bytes)}`);
+      if (deps.layout.prefixOf(key) !== input.prefix) throw new StorageError(STORAGE_CODE.badPrefix, `\xAB ${input.prefix} \xBB is not a declared prefix`);
+      await deps.store.put(key, input.bytes, { contentType: actual });
+      return { key, contentType: actual, size: input.bytes.byteLength, url: await urlFor(key) };
+    },
+    urlFor,
+    get: (key) => deps.store.get(key),
+    head: (key) => deps.store.head(key),
+    delete: (key) => deps.store.delete(key),
+    list: (prefix) => deps.store.list(prefix)
+  };
+}
+
+// src/vault.ts
+import { createCipheriv, createDecipheriv, randomBytes } from "crypto";
+var parseVaultKey = (base64) => parseSecretKey(base64, "The vault key");
+function seal(secret, key) {
+  const iv = randomBytes(12);
+  const cipher = createCipheriv("aes-256-gcm", key, iv);
+  const body = Buffer.concat([cipher.update(secret, "utf8"), cipher.final()]);
+  return `v1.${Buffer.concat([iv, cipher.getAuthTag(), body]).toString("base64url")}`;
+}
+function open(sealed, key) {
+  if (!sealed.startsWith("v1.")) throw new StorageError(STORAGE_CODE.unreadable, "Unreadable sealed value");
+  try {
+    const raw = Buffer.from(sealed.slice(3), "base64url");
+    const decipher = createDecipheriv("aes-256-gcm", key, raw.subarray(0, 12));
+    decipher.setAuthTag(raw.subarray(12, 28));
+    return Buffer.concat([decipher.update(raw.subarray(28)), decipher.final()]).toString("utf8");
+  } catch {
+    throw new StorageError(STORAGE_CODE.unreadable, "The sealed value failed its integrity check");
+  }
+}
+export {
+  COUNTRY_OF_REGION,
+  STORAGE_CODE,
+  STORE_KIND,
+  StorageError,
+  assertKey,
+  bucketStore,
+  checkEndpoint,
+  countryOf,
+  createStorage,
+  defineLayout,
+  describeStore,
+  encryptedStore,
+  folderStore,
+  hashOf,
+  hashedName,
+  memoryObjectStore,
+  open,
+  parseEncryptionKey,
+  parseVaultKey,
+  remoteStore,
+  residencyOf,
+  residencyOfConfig,
+  seal,
+  sniffType,
+  storageNotice,
+  trimSlashes,
+  typeOfName,
+  where
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/memory-store.ts","../src/sniff.ts","../src/storage.ts","../src/vault.ts"],"sourcesContent":["import { assertKey, trimSlashes, typeOfName } from \"./keys\";\nimport type { ObjectStore } from \"./port\";\n\n/** An in-memory store, for unit tests and demos: the behaviour of the others (the contract kit runs on all). */\nexport function memoryObjectStore(options: { publicBaseUrl?: string } = {}): ObjectStore {\n  const files = new Map<string, { bytes: Uint8Array; contentType: string }>();\n  return {\n    async put(key, bytes, meta) {\n      files.set(assertKey(key), { bytes: new Uint8Array(bytes), contentType: meta.contentType });\n    },\n    async get(key) {\n      const f = files.get(assertKey(key));\n      return f ? { bytes: new Uint8Array(f.bytes), contentType: f.contentType || typeOfName(key) } : null;\n    },\n    async head(key) {\n      const f = files.get(assertKey(key));\n      return f ? { key, size: f.bytes.byteLength } : null;\n    },\n    async delete(key) {\n      files.delete(assertKey(key));\n    },\n    async list(prefix) {\n      return [...files.entries()]\n        .filter(([key]) => key.startsWith(prefix))\n        .map(([key, f]) => ({ key, size: f.bytes.byteLength }))\n        .sort((a, b) => a.key.localeCompare(b.key));\n    },\n    async signedUrl() {\n      return null;\n    },\n    publicUrl: (key) => (options.publicBaseUrl ? `${trimSlashes(options.publicBaseUrl, \"end\")}/${assertKey(key)}` : null),\n  };\n}\n","const startsWith = (bytes: Uint8Array, signature: readonly number[], offset = 0) => signature.every((b, i) => bytes[offset + i] === b);\nconst ascii = (bytes: Uint8Array, from: number, to: number) => String.fromCharCode(...bytes.subarray(from, to));\n\n/**\n * The content type the BYTES say they are, by magic number, never by the file name: png, jpeg, gif, webp, pdf, mp4, webm and svg.\n * `null` when the bytes are none of these. An svg is text that opens with `<svg` (or an xml declaration followed by it).\n */\nexport function sniffType(bytes: Uint8Array): string | null {\n  if (startsWith(bytes, [0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a])) return \"image/png\";\n  if (startsWith(bytes, [0xff, 0xd8, 0xff])) return \"image/jpeg\";\n  if (ascii(bytes, 0, 4) === \"GIF8\") return \"image/gif\";\n  if (ascii(bytes, 0, 4) === \"RIFF\" && ascii(bytes, 8, 12) === \"WEBP\") return \"image/webp\";\n  if (ascii(bytes, 0, 5) === \"%PDF-\") return \"application/pdf\";\n  if (ascii(bytes, 4, 8) === \"ftyp\") return \"video/mp4\";\n  if (startsWith(bytes, [0x1a, 0x45, 0xdf, 0xa3])) return \"video/webm\";\n  const head = new TextDecoder(\"utf-8\", { fatal: false }).decode(bytes.subarray(0, 512)).replace(\"\\uFEFF\", \"\").trimStart();\n  if (startsSvg(head)) return \"image/svg+xml\";\n  return null;\n}\n\n/** Whether text opens as an SVG document: an optional XML declaration and comments, then `<svg`. Read with indexOf, never a backtracking pattern. */\nfunction startsSvg(text: string): boolean {\n  let rest = text;\n  if (rest.startsWith(\"<?xml\")) {\n    const end = rest.indexOf(\"?>\");\n    if (end < 0) return false;\n    rest = rest.slice(end + 2).trimStart();\n  }\n  while (rest.startsWith(\"<!--\")) {\n    const end = rest.indexOf(\"-->\");\n    if (end < 0) return false;\n    rest = rest.slice(end + 3).trimStart();\n  }\n  return /^<svg[\\s>]/i.test(rest);\n}\n","import { hashedName, type Layout } from \"./keys\";\nimport { type ObjectStore, STORAGE_CODE, StorageError } from \"./port\";\nimport { sniffType } from \"./sniff\";\n\nexport interface StorageLimits {\n  /** The largest file accepted, in bytes. */\n  maxBytes: number;\n  /** Seconds a signed link lives. */\n  signedUrlSeconds: number;\n}\n\nexport interface StorageDeps {\n  store: ObjectStore;\n  layout: Layout;\n  /** Read at each call so the admin's change applies at once. */\n  limits: StorageLimits | (() => StorageLimits | Promise<StorageLimits>);\n}\n\nexport interface UploadInput {\n  /** The layout prefix the file goes under (`site/home/`). */\n  prefix: string;\n  /** The name the file arrives with; the stored name is `<name>.<sha10>.<ext>`. */\n  name: string;\n  bytes: Uint8Array;\n  /** The content types this upload may be: the BYTES must be one of them, whatever the name or the declared type say. */\n  allow: readonly string[];\n  /** The type the client declared, when it did: it must agree with the bytes. */\n  declaredType?: string;\n}\n\nexport interface Storage {\n  /** Checks the size, the prefix and the bytes' magic number, then stores the file under a content-hashed name. Answers its key, and a link when one exists. */\n  upload(input: UploadInput): Promise<{ key: string; contentType: string; size: number; url: string | null }>;\n  /** The public link when the zone has one, else a signed link, else `null`. */\n  urlFor(key: string): Promise<string | null>;\n  get: ObjectStore[\"get\"];\n  head: ObjectStore[\"head\"];\n  delete: ObjectStore[\"delete\"];\n  list: ObjectStore[\"list\"];\n}\n\n/**\n * The storage of a product: an `ObjectStore` with the rules every upload obeys (a size limit passed in, a declared layout, bytes\n * checked by magic number, a content-hashed name).\n */\nexport function createStorage(deps: StorageDeps): Storage {\n  const limits = async () => (typeof deps.limits === \"function\" ? await deps.limits() : deps.limits);\n  const urlFor = async (key: string) => deps.store.publicUrl(key) ?? (await deps.store.signedUrl(key, (await limits()).signedUrlSeconds));\n  return {\n    async upload(input) {\n      const { maxBytes } = await limits();\n      if (input.bytes.byteLength === 0 || input.bytes.byteLength > maxBytes) throw new StorageError(STORAGE_CODE.tooBig, `a file is 1 to ${maxBytes} bytes`);\n      const actual = sniffType(input.bytes);\n      if (actual === null || !input.allow.includes(actual)) throw new StorageError(STORAGE_CODE.badType, `the bytes are ${actual ?? \"of an unknown type\"}, not one of ${input.allow.join(\", \")}`);\n      if (input.declaredType !== undefined && input.declaredType !== actual) throw new StorageError(STORAGE_CODE.typeMismatch, `declared ${input.declaredType}, the bytes are ${actual}`);\n      const key = deps.layout.check(`${input.prefix}${hashedName(input.name, input.bytes)}`);\n      if (deps.layout.prefixOf(key) !== input.prefix) throw new StorageError(STORAGE_CODE.badPrefix, `« ${input.prefix} » is not a declared prefix`);\n      await deps.store.put(key, input.bytes, { contentType: actual });\n      return { key, contentType: actual, size: input.bytes.byteLength, url: await urlFor(key) };\n    },\n    urlFor,\n    get: (key) => deps.store.get(key),\n    head: (key) => deps.store.head(key),\n    delete: (key) => deps.store.delete(key),\n    list: (prefix) => deps.store.list(prefix),\n  };\n}\n","import { createCipheriv, createDecipheriv, randomBytes } from \"node:crypto\";\n\nimport { STORAGE_CODE, StorageError } from \"./port\";\nimport { parseSecretKey } from \"./secret-key\";\n\n/** The 32-byte key of the vault, from its base64 form (the deployment's, passed in). */\nexport const parseVaultKey = (base64: string): Uint8Array => parseSecretKey(base64, \"The vault key\");\n\n/**\n * Seals a credential for the database (AES-256-GCM, a fresh IV, `v1.<iv|tag|ciphertext>` in base64url). A leaked table opens\n * nothing, and a sealed value is never sent back to the browser: the admin screen shows « set » or « not set ».\n */\nexport function seal(secret: string, key: Uint8Array): string {\n  const iv = randomBytes(12);\n  const cipher = createCipheriv(\"aes-256-gcm\", key, iv);\n  const body = Buffer.concat([cipher.update(secret, \"utf8\"), cipher.final()]);\n  return `v1.${Buffer.concat([iv, cipher.getAuthTag(), body]).toString(\"base64url\")}`;\n}\n\n/** @throws StorageError `STORAGE_UNREADABLE` for a value that is not sealed, was tampered with, or sealed under another key */\nexport function open(sealed: string, key: Uint8Array): string {\n  if (!sealed.startsWith(\"v1.\")) throw new StorageError(STORAGE_CODE.unreadable, \"Unreadable sealed value\");\n  try {\n    const raw = Buffer.from(sealed.slice(3), \"base64url\");\n    const decipher = createDecipheriv(\"aes-256-gcm\", key, raw.subarray(0, 12));\n    decipher.setAuthTag(raw.subarray(12, 28));\n    return Buffer.concat([decipher.update(raw.subarray(28)), decipher.final()]).toString(\"utf8\");\n  } catch {\n    throw new StorageError(STORAGE_CODE.unreadable, \"The sealed value failed its integrity check\");\n  }\n}\n"],"mappings":"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","names":[]}

package/dist/port-6VXXuSbc.d.ts

@@ -0,0 +1,65 @@
+/**
+ * The ports of « storage »: files behind one interface, named by what it does. Generic: no vendor SDK (adapters speak plain HTTP
+ * through an injected `fetch`), no environment variable (credentials come in as parameters), no wall clock (a `Clock` signs the links).
+ */
+
+/** The part of `fetch` the adapters use: inject the global one (`fetch`), or a fake in a test. */
+type FetchLike = (url: string, init: {
+    method: string;
+    headers: Record<string, string>;
+    body?: Uint8Array;
+}) => Promise<{
+    ok: boolean;
+    status: number;
+    headers: {
+        get(name: string): string | null;
+    };
+    arrayBuffer(): Promise<ArrayBuffer>;
+    text(): Promise<string>;
+}>;
+interface StoredObject {
+    bytes: Uint8Array;
+    contentType: string;
+}
+interface ObjectInfo {
+    key: string;
+    size: number;
+}
+/** One place files live. Every adapter runs `objectStoreContract` (`@krizaka/storage/testkit`). Keys are `a/b/name.ext`, checked by `assertKey`. */
+interface ObjectStore {
+    put(key: string, bytes: Uint8Array, meta: {
+        contentType: string;
+    }): Promise<void>;
+    /** `null` when there is no such file. */
+    get(key: string): Promise<StoredObject | null>;
+    head(key: string): Promise<ObjectInfo | null>;
+    /** Idempotent: deleting a missing file is not an error. */
+    delete(key: string): Promise<void>;
+    /** Every file whose key starts with `prefix`, in key order, directories flattened. */
+    list(prefix: string): Promise<ObjectInfo[]>;
+    /** A link valid for `ttlSeconds` for a private file, or `null` when the store cannot sign one. */
+    signedUrl(key: string, ttlSeconds: number): Promise<string | null>;
+    /** The permanent public link (a pull zone, a CDN), or `null` when the zone is private. */
+    publicUrl(key: string): string | null;
+}
+/** The refusals of this package: a stable `code`, and the HTTP status a route would answer. */
+declare const STORAGE_CODE: {
+    readonly badKey: "STORAGE_BAD_KEY";
+    readonly badPrefix: "STORAGE_BAD_PREFIX";
+    readonly tooBig: "STORAGE_TOO_BIG";
+    readonly badType: "STORAGE_BAD_TYPE";
+    readonly typeMismatch: "STORAGE_TYPE_MISMATCH";
+    readonly provider: "STORAGE_PROVIDER_FAILED";
+    readonly badConfig: "STORAGE_BAD_CONFIG";
+    readonly badEndpoint: "STORAGE_BAD_ENDPOINT";
+    readonly badSecretKey: "STORAGE_BAD_SECRET_KEY";
+    readonly unreadable: "STORAGE_UNREADABLE";
+    readonly keepingOff: "STORAGE_KEEPING_OFF";
+};
+type StorageCode = (typeof STORAGE_CODE)[keyof typeof STORAGE_CODE];
+declare class StorageError extends Error {
+    readonly code: StorageCode;
+    constructor(code: StorageCode, message: string);
+}
+
+export { type FetchLike as F, type ObjectStore as O, STORAGE_CODE as S, type ObjectInfo as a, type StorageCode as b, StorageError as c, type StoredObject as d };

package/dist/resolve.d.ts

@@ -0,0 +1,74 @@
+import { F as FetchLike, O as ObjectStore } from './port-6VXXuSbc.js';
+import { StorageSettings } from './settings.js';
+import { a as StoreDescriptor } from './where-DKtS1O5l.js';
+import { Clock } from '@krizaka/db';
+import '@krizaka/settings';
+import './storage-DurtrQKq.js';
+
+/**
+ * What a deployment's environment says about one kind of kept data (documents, avatars, exports…), read by the product's edge and
+ * passed in: this module reads no environment. `provider: "none"` is « keeping is off here ».
+ */
+interface DeploymentStorage {
+    environment: "dev" | "prod";
+    provider: "none" | "http" | "s3";
+    prefix?: string;
+    /** 32 bytes in base64: when set, everything is encrypted before it leaves. */
+    encryptionKey?: string;
+    http?: {
+        endpoint?: string;
+        zone?: string;
+        accessKey?: string;
+        pullHostname?: string;
+        tokenKey?: string;
+    };
+    s3?: {
+        endpoint?: string;
+        region?: string;
+        bucket?: string;
+        accessKeyId?: string;
+        secretAccessKey?: string;
+    };
+}
+/** A signed link never lives longer than this, whatever the admin or a caller asks (a kept file is personal data). */
+declare const DEFAULT_MAX_SIGNED_SECONDS = 900;
+type ResolvedStorage = {
+    provider: "none";
+} | {
+    provider: "http" | "s3";
+    settings: StorageSettings;
+    secrets: {
+        accessKeyId?: string;
+        secretAccessKey?: string;
+        accessKey?: string;
+        tokenKey?: string;
+    };
+    descriptor: StoreDescriptor;
+};
+/**
+ * The provider that applies to a kind of data, from the admin's settings over the deployment's environment. The same function serves
+ * every kind (documents, avatars): the admin's choice in `storage.*` wins for each, the environment supplies the secrets and the
+ * fallback when the admin left `local`.
+ *
+ * The environment can switch keeping off (`provider: "none"`), and the admin cannot override that: an admin who picks `http` or `s3`
+ * while the environment says `none` is refused with `STORAGE_KEEPING_OFF`, never silently ignored (the screen would say « kept »
+ * while nothing is) and never silently turned on (a deployment that was told not to keep files would start to). Changing the
+ * environment is the way to turn keeping on. Call this when saving the settings to refuse early, and again to open the store.
+ * @throws StorageError `STORAGE_KEEPING_OFF`
+ */
+declare function resolveStorage(env: DeploymentStorage, admin: StorageSettings | null, options?: {
+    maxSignedSeconds?: number;
+}): ResolvedStorage;
+/**
+ * The store of a resolved configuration, encrypted when the environment holds a key, with the descriptor the product says. `null` when
+ * keeping is off. A provider without its coordinates or keys is refused (`STORAGE_BAD_CONFIG`), never replaced by another.
+ */
+declare function openResolved(resolved: ResolvedStorage, env: DeploymentStorage, deps: {
+    fetch: FetchLike;
+    clock: Clock;
+}): {
+    store: ObjectStore;
+    descriptor: StoreDescriptor;
+} | null;
+
+export { DEFAULT_MAX_SIGNED_SECONDS, type DeploymentStorage, type ResolvedStorage, openResolved, resolveStorage };

package/dist/resolve.js

@@ -0,0 +1,52 @@
+import {
+  describeStore,
+  encryptedStore,
+  parseEncryptionKey
+} from "./chunk-C3LEYKGC.js";
+import {
+  storeFromSettings
+} from "./chunk-ZWQMALDF.js";
+import {
+  STORAGE_CODE,
+  StorageError
+} from "./chunk-W56662PQ.js";
+
+// src/resolve.ts
+var DEFAULT_MAX_SIGNED_SECONDS = 900;
+function resolveStorage(env, admin, options = {}) {
+  const adminProvider = admin && admin.provider !== "local" ? admin.provider : null;
+  if (env.provider === "none") {
+    if (adminProvider) throw new StorageError(STORAGE_CODE.keepingOff, `The admin chose storage.provider ${adminProvider}, but this deployment has keeping turned off (provider none): turn it on in the environment first`);
+    return { provider: "none" };
+  }
+  const provider = adminProvider ?? env.provider;
+  const pick = (own, fallback) => own ? own : fallback ?? "";
+  const http = provider === "http";
+  const settings = {
+    provider,
+    maxMegabytes: admin?.maxMegabytes ?? 25,
+    // @fixed: the settings default, the admin changes it
+    signedUrlSeconds: Math.min(admin?.signedUrlSeconds ?? Infinity, options.maxSignedSeconds ?? DEFAULT_MAX_SIGNED_SECONDS),
+    endpoint: http ? pick(admin?.endpoint, env.http?.endpoint) : pick(admin?.endpoint, env.s3?.endpoint),
+    region: pick(admin?.region, env.s3?.region),
+    bucket: pick(admin?.bucket, env.s3?.bucket),
+    zone: pick(admin?.zone, env.http?.zone),
+    prefix: pick(admin?.prefix, env.prefix),
+    pullHostname: pick(admin?.pullHostname, env.http?.pullHostname),
+    publicBaseUrl: admin?.publicBaseUrl ?? ""
+  };
+  const secrets = { ...env.s3, ...env.http };
+  return { provider, settings, secrets: { accessKeyId: secrets.accessKeyId, secretAccessKey: secrets.secretAccessKey, accessKey: secrets.accessKey, tokenKey: secrets.tokenKey }, descriptor: describeStore({ provider, endpoint: settings.endpoint, region: settings.region }, { encrypted: !!env.encryptionKey }) };
+}
+function openResolved(resolved, env, deps) {
+  if (resolved.provider === "none") return null;
+  const objects = storeFromSettings(resolved.settings, resolved.secrets, { ...deps, allowLocalEndpoint: env.environment === "dev" });
+  const store = env.encryptionKey ? encryptedStore(objects, parseEncryptionKey(env.encryptionKey)) : objects;
+  return { store, descriptor: resolved.descriptor };
+}
+export {
+  DEFAULT_MAX_SIGNED_SECONDS,
+  openResolved,
+  resolveStorage
+};
+//# sourceMappingURL=resolve.js.map

package/dist/resolve.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/resolve.ts"],"sourcesContent":["import { encryptedStore, parseEncryptionKey } from \"./encrypted-store\";\nimport { type Clock, type FetchLike, type ObjectStore, STORAGE_CODE, StorageError } from \"./port\";\nimport { type StorageSettings, storeFromSettings } from \"./settings\";\nimport { describeStore, type StoreDescriptor } from \"./where\";\n\n/**\n * What a deployment's environment says about one kind of kept data (documents, avatars, exports…), read by the product's edge and\n * passed in: this module reads no environment. `provider: \"none\"` is « keeping is off here ».\n */\nexport interface DeploymentStorage {\n  environment: \"dev\" | \"prod\";\n  provider: \"none\" | \"http\" | \"s3\";\n  prefix?: string;\n  /** 32 bytes in base64: when set, everything is encrypted before it leaves. */\n  encryptionKey?: string;\n  http?: { endpoint?: string; zone?: string; accessKey?: string; pullHostname?: string; tokenKey?: string };\n  s3?: { endpoint?: string; region?: string; bucket?: string; accessKeyId?: string; secretAccessKey?: string };\n}\n\n/** A signed link never lives longer than this, whatever the admin or a caller asks (a kept file is personal data). */\n// @fixed: a link to personal data that outlives a reading session is a leak\nexport const DEFAULT_MAX_SIGNED_SECONDS = 900;\n\nexport type ResolvedStorage = { provider: \"none\" } | { provider: \"http\" | \"s3\"; settings: StorageSettings; secrets: { accessKeyId?: string; secretAccessKey?: string; accessKey?: string; tokenKey?: string }; descriptor: StoreDescriptor };\n\n/**\n * The provider that applies to a kind of data, from the admin's settings over the deployment's environment. The same function serves\n * every kind (documents, avatars): the admin's choice in `storage.*` wins for each, the environment supplies the secrets and the\n * fallback when the admin left `local`.\n *\n * The environment can switch keeping off (`provider: \"none\"`), and the admin cannot override that: an admin who picks `http` or `s3`\n * while the environment says `none` is refused with `STORAGE_KEEPING_OFF`, never silently ignored (the screen would say « kept »\n * while nothing is) and never silently turned on (a deployment that was told not to keep files would start to). Changing the\n * environment is the way to turn keeping on. Call this when saving the settings to refuse early, and again to open the store.\n * @throws StorageError `STORAGE_KEEPING_OFF`\n */\nexport function resolveStorage(env: DeploymentStorage, admin: StorageSettings | null, options: { maxSignedSeconds?: number } = {}): ResolvedStorage {\n  const adminProvider = admin && admin.provider !== \"local\" ? admin.provider : null;\n  if (env.provider === \"none\") {\n    if (adminProvider) throw new StorageError(STORAGE_CODE.keepingOff, `The admin chose storage.provider ${adminProvider}, but this deployment has keeping turned off (provider none): turn it on in the environment first`);\n    return { provider: \"none\" };\n  }\n  const provider = adminProvider ?? env.provider;\n  const pick = (own: string | undefined, fallback: string | undefined) => (own ? own : (fallback ?? \"\"));\n  const http = provider === \"http\";\n  const settings: StorageSettings = {\n    provider,\n    maxMegabytes: admin?.maxMegabytes ?? 25, // @fixed: the settings default, the admin changes it\n    signedUrlSeconds: Math.min(admin?.signedUrlSeconds ?? Infinity, options.maxSignedSeconds ?? DEFAULT_MAX_SIGNED_SECONDS),\n    endpoint: http ? pick(admin?.endpoint, env.http?.endpoint) : pick(admin?.endpoint, env.s3?.endpoint),\n    region: pick(admin?.region, env.s3?.region),\n    bucket: pick(admin?.bucket, env.s3?.bucket),\n    zone: pick(admin?.zone, env.http?.zone),\n    prefix: pick(admin?.prefix, env.prefix),\n    pullHostname: pick(admin?.pullHostname, env.http?.pullHostname),\n    publicBaseUrl: admin?.publicBaseUrl ?? \"\",\n  };\n  const secrets = { ...env.s3, ...env.http };\n  return { provider, settings, secrets: { accessKeyId: secrets.accessKeyId, secretAccessKey: secrets.secretAccessKey, accessKey: secrets.accessKey, tokenKey: secrets.tokenKey }, descriptor: describeStore({ provider, endpoint: settings.endpoint, region: settings.region }, { encrypted: !!env.encryptionKey }) };\n}\n\n/**\n * The store of a resolved configuration, encrypted when the environment holds a key, with the descriptor the product says. `null` when\n * keeping is off. A provider without its coordinates or keys is refused (`STORAGE_BAD_CONFIG`), never replaced by another.\n */\nexport function openResolved(resolved: ResolvedStorage, env: DeploymentStorage, deps: { fetch: FetchLike; clock: Clock }): { store: ObjectStore; descriptor: StoreDescriptor } | null {\n  if (resolved.provider === \"none\") return null;\n  const objects = storeFromSettings(resolved.settings, resolved.secrets, { ...deps, allowLocalEndpoint: env.environment === \"dev\" });\n  const store = env.encryptionKey ? encryptedStore(objects, parseEncryptionKey(env.encryptionKey)) : objects;\n  return { store, descriptor: resolved.descriptor };\n}\n"],"mappings":";;;;;;;;;;;;;;AAqBO,IAAM,6BAA6B;AAenC,SAAS,eAAe,KAAwB,OAA+B,UAAyC,CAAC,GAAoB;AAClJ,QAAM,gBAAgB,SAAS,MAAM,aAAa,UAAU,MAAM,WAAW;AAC7E,MAAI,IAAI,aAAa,QAAQ;AAC3B,QAAI,cAAe,OAAM,IAAI,aAAa,aAAa,YAAY,oCAAoC,aAAa,mGAAmG;AACvN,WAAO,EAAE,UAAU,OAAO;AAAA,EAC5B;AACA,QAAM,WAAW,iBAAiB,IAAI;AACtC,QAAM,OAAO,CAAC,KAAyB,aAAkC,MAAM,MAAO,YAAY;AAClG,QAAM,OAAO,aAAa;AAC1B,QAAM,WAA4B;AAAA,IAChC;AAAA,IACA,cAAc,OAAO,gBAAgB;AAAA;AAAA,IACrC,kBAAkB,KAAK,IAAI,OAAO,oBAAoB,UAAU,QAAQ,oBAAoB,0BAA0B;AAAA,IACtH,UAAU,OAAO,KAAK,OAAO,UAAU,IAAI,MAAM,QAAQ,IAAI,KAAK,OAAO,UAAU,IAAI,IAAI,QAAQ;AAAA,IACnG,QAAQ,KAAK,OAAO,QAAQ,IAAI,IAAI,MAAM;AAAA,IAC1C,QAAQ,KAAK,OAAO,QAAQ,IAAI,IAAI,MAAM;AAAA,IAC1C,MAAM,KAAK,OAAO,MAAM,IAAI,MAAM,IAAI;AAAA,IACtC,QAAQ,KAAK,OAAO,QAAQ,IAAI,MAAM;AAAA,IACtC,cAAc,KAAK,OAAO,cAAc,IAAI,MAAM,YAAY;AAAA,IAC9D,eAAe,OAAO,iBAAiB;AAAA,EACzC;AACA,QAAM,UAAU,EAAE,GAAG,IAAI,IAAI,GAAG,IAAI,KAAK;AACzC,SAAO,EAAE,UAAU,UAAU,SAAS,EAAE,aAAa,QAAQ,aAAa,iBAAiB,QAAQ,iBAAiB,WAAW,QAAQ,WAAW,UAAU,QAAQ,SAAS,GAAG,YAAY,cAAc,EAAE,UAAU,UAAU,SAAS,UAAU,QAAQ,SAAS,OAAO,GAAG,EAAE,WAAW,CAAC,CAAC,IAAI,cAAc,CAAC,EAAE;AACpT;AAMO,SAAS,aAAa,UAA2B,KAAwB,MAAsG;AACpL,MAAI,SAAS,aAAa,OAAQ,QAAO;AACzC,QAAM,UAAU,kBAAkB,SAAS,UAAU,SAAS,SAAS,EAAE,GAAG,MAAM,oBAAoB,IAAI,gBAAgB,MAAM,CAAC;AACjI,QAAM,QAAQ,IAAI,gBAAgB,eAAe,SAAS,mBAAmB,IAAI,aAAa,CAAC,IAAI;AACnG,SAAO,EAAE,OAAO,YAAY,SAAS,WAAW;AAClD;","names":[]}

package/dist/settings.d.ts

@@ -0,0 +1,68 @@
+import * as _krizaka_settings from '@krizaka/settings';
+import { F as FetchLike, O as ObjectStore } from './port-6VXXuSbc.js';
+import { b as StorageLimits } from './storage-DurtrQKq.js';
+import { Clock } from '@krizaka/db';
+
+declare const STORAGE_PROVIDERS: readonly ["local", "http", "s3"];
+declare const STORAGE_DEFAULTS: {
+    readonly provider: "local";
+    readonly maxMegabytes: 25;
+    readonly signedUrlSeconds: 300;
+};
+/**
+ * The settings of « storage », a fragment the product adds to its registry (`@krizaka/storage/settings`): the admin picks the provider
+ * (`local`, `http` for a Bunny-style zone, `s3` for any S3-compatible bucket) and its non-secret coordinates, without a redeploy.
+ * Access keys and the token key stay in the environment and are passed to `storeFromSettings`.
+ */
+declare const storageSettings: {
+    readonly "storage.provider": _krizaka_settings.Def<"local" | "http" | "s3">;
+    readonly "storage.maxMegabytes": _krizaka_settings.Def<number>;
+    readonly "storage.signedUrlSeconds": _krizaka_settings.Def<number>;
+    readonly "storage.endpoint": _krizaka_settings.Def<string>;
+    readonly "storage.region": _krizaka_settings.Def<string>;
+    readonly "storage.bucket": _krizaka_settings.Def<string>;
+    readonly "storage.zone": _krizaka_settings.Def<string>;
+    readonly "storage.prefix": _krizaka_settings.Def<string>;
+    readonly "storage.pullHostname": _krizaka_settings.Def<string>;
+    readonly "storage.publicBaseUrl": _krizaka_settings.Def<string>;
+};
+interface StorageSettings {
+    provider: (typeof STORAGE_PROVIDERS)[number];
+    maxMegabytes: number;
+    signedUrlSeconds: number;
+    endpoint: string;
+    region: string;
+    bucket: string;
+    zone: string;
+    prefix: string;
+    pullHostname: string;
+    publicBaseUrl: string;
+}
+type Reader = (key: keyof typeof storageSettings) => string | number | undefined | Promise<string | number | undefined>;
+/** The module's settings from the product's accessor (`(key) => service.get(key, ctx)`); an unknown key falls back to the default. */
+declare function readStorageSettings(read: Reader): Promise<StorageSettings>;
+declare const limitsOf: (s: StorageSettings) => StorageLimits;
+/** The credentials the product reads from its environment and passes in. */
+interface StorageSecrets {
+    accessKeyId?: string;
+    secretAccessKey?: string;
+    /** The zone's password (`http`). */
+    accessKey?: string;
+    /** The pull zone's token-authentication key (`http`). */
+    tokenKey?: string;
+    /** The folder for `local`. */
+    root?: string;
+}
+/**
+ * The store the admin chose. A provider chosen without its coordinates or keys is refused loudly, never replaced by another: a file
+ * must not land somewhere nobody expects. The `http` endpoint is the host only (`storage.bunnycdn.com`); an `s3` endpoint is checked
+ * against our own network (`checkEndpoint`) unless `allowLocalEndpoint` (development).
+ * @throws StorageError `STORAGE_BAD_CONFIG` or `STORAGE_BAD_ENDPOINT`
+ */
+declare function storeFromSettings(s: StorageSettings, secrets: StorageSecrets, deps: {
+    fetch: FetchLike;
+    clock: Clock;
+    allowLocalEndpoint?: boolean;
+}): ObjectStore;
+
+export { STORAGE_DEFAULTS, STORAGE_PROVIDERS, type StorageSecrets, type StorageSettings, limitsOf, readStorageSettings, storageSettings, storeFromSettings };

package/dist/settings.js

@@ -0,0 +1,18 @@
+import {
+  STORAGE_DEFAULTS,
+  STORAGE_PROVIDERS,
+  limitsOf,
+  readStorageSettings,
+  storageSettings,
+  storeFromSettings
+} from "./chunk-ZWQMALDF.js";
+import "./chunk-W56662PQ.js";
+export {
+  STORAGE_DEFAULTS,
+  STORAGE_PROVIDERS,
+  limitsOf,
+  readStorageSettings,
+  storageSettings,
+  storeFromSettings
+};
+//# sourceMappingURL=settings.js.map

package/dist/settings.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/storage-DurtrQKq.d.ts

@@ -0,0 +1,73 @@
+import { O as ObjectStore } from './port-6VXXuSbc.js';
+
+/** Trims slashes at the ends without a regular expression (a long run of slashes must not be quadratic). */
+declare function trimSlashes(value: string, ends?: "both" | "end"): string;
+/**
+ * A key is `a/b/name.ext`: no empty segment, no `.` or `..`, no leading or trailing slash, no backslash, no control character.
+ * @throws StorageError `STORAGE_BAD_KEY`
+ */
+declare function assertKey(key: string): string;
+/** The first 10 hex characters of the SHA-256: the rule of the Krizaka media library (`name.<hash>.ext`). */
+declare const hashOf: (bytes: Uint8Array) => string;
+/** `photo.jpg` and its bytes give `photo.<sha10>.jpg`: a URL never changes content, so it is cached for good. */
+declare function hashedName(name: string, bytes: Uint8Array): string;
+/**
+ * The prefixes a zone allows, as data: an unknown prefix is refused. A layout lists prefixes WITH a trailing slash (`site/home/`);
+ * a key belongs to the prefix it starts with.
+ */
+interface Layout {
+    prefixes: readonly string[];
+    /** The prefix a key belongs to, or `null`. */
+    prefixOf(key: string): string | null;
+    /** @throws StorageError `STORAGE_BAD_PREFIX` when the key is under no declared prefix. */
+    check(key: string): string;
+}
+declare function defineLayout(prefixes: readonly string[]): Layout;
+/** The content type a file name suggests, for stores that do not keep one. Never a security decision: see `sniffType`. */
+declare const typeOfName: (key: string) => string;
+
+interface StorageLimits {
+    /** The largest file accepted, in bytes. */
+    maxBytes: number;
+    /** Seconds a signed link lives. */
+    signedUrlSeconds: number;
+}
+interface StorageDeps {
+    store: ObjectStore;
+    layout: Layout;
+    /** Read at each call so the admin's change applies at once. */
+    limits: StorageLimits | (() => StorageLimits | Promise<StorageLimits>);
+}
+interface UploadInput {
+    /** The layout prefix the file goes under (`site/home/`). */
+    prefix: string;
+    /** The name the file arrives with; the stored name is `<name>.<sha10>.<ext>`. */
+    name: string;
+    bytes: Uint8Array;
+    /** The content types this upload may be: the BYTES must be one of them, whatever the name or the declared type say. */
+    allow: readonly string[];
+    /** The type the client declared, when it did: it must agree with the bytes. */
+    declaredType?: string;
+}
+interface Storage {
+    /** Checks the size, the prefix and the bytes' magic number, then stores the file under a content-hashed name. Answers its key, and a link when one exists. */
+    upload(input: UploadInput): Promise<{
+        key: string;
+        contentType: string;
+        size: number;
+        url: string | null;
+    }>;
+    /** The public link when the zone has one, else a signed link, else `null`. */
+    urlFor(key: string): Promise<string | null>;
+    get: ObjectStore["get"];
+    head: ObjectStore["head"];
+    delete: ObjectStore["delete"];
+    list: ObjectStore["list"];
+}
+/**
+ * The storage of a product: an `ObjectStore` with the rules every upload obeys (a size limit passed in, a declared layout, bytes
+ * checked by magic number, a content-hashed name).
+ */
+declare function createStorage(deps: StorageDeps): Storage;
+
+export { type Layout as L, type Storage as S, type UploadInput as U, type StorageDeps as a, type StorageLimits as b, assertKey as c, createStorage as d, defineLayout as e, hashedName as f, typeOfName as g, hashOf as h, trimSlashes as t };

package/dist/testkit.d.ts

@@ -0,0 +1,6 @@
+import { O as ObjectStore } from './port-6VXXuSbc.js';
+
+/** What every `ObjectStore` adapter must do: the same behaviour behind the same port. `make` gives an empty store. */
+declare function objectStoreContract(name: string, make: () => ObjectStore | Promise<ObjectStore>): void;
+
+export { objectStoreContract };

package/dist/testkit.js

@@ -0,0 +1,44 @@
+// src/testkit.ts
+import { expect, it } from "vitest";
+var bytes = (...n) => new Uint8Array(n);
+function objectStoreContract(name, make) {
+  it(`${name}: stores a file and reads it back byte for byte`, async () => {
+    const store = await make();
+    await store.put("site/home/a.b1.png", bytes(1, 2, 3, 255), { contentType: "image/png" });
+    const got = await store.get("site/home/a.b1.png");
+    expect([...got.bytes]).toEqual([1, 2, 3, 255]);
+    expect(got.contentType).toBe("image/png");
+    expect(await store.head("site/home/a.b1.png")).toEqual({ key: "site/home/a.b1.png", size: 4 });
+  });
+  it(`${name}: answers null for a missing file, and deleting it twice is fine`, async () => {
+    const store = await make();
+    expect(await store.get("missing/file.txt")).toBeNull();
+    expect(await store.head("missing/file.txt")).toBeNull();
+    await store.put("x/y.txt", bytes(1), { contentType: "text/plain" });
+    await store.delete("x/y.txt");
+    await store.delete("x/y.txt");
+    expect(await store.get("x/y.txt")).toBeNull();
+  });
+  it(`${name}: overwrites a key`, async () => {
+    const store = await make();
+    await store.put("k/f.bin", bytes(1), { contentType: "application/octet-stream" });
+    await store.put("k/f.bin", bytes(9, 9), { contentType: "application/octet-stream" });
+    expect([...(await store.get("k/f.bin")).bytes]).toEqual([9, 9]);
+  });
+  it(`${name}: lists the files under a prefix, directories flattened, in key order`, async () => {
+    const store = await make();
+    for (const key of ["a/one.txt", "a/b/two.txt", "a/b/c/three.txt", "other/four.txt", "a-b/five.txt"]) await store.put(key, bytes(7), { contentType: "text/plain" });
+    expect((await store.list("a/")).map((f) => f.key)).toEqual(["a/b/c/three.txt", "a/b/two.txt", "a/one.txt"]);
+    expect((await store.list("a/b/")).map((f) => f.key)).toEqual(["a/b/c/three.txt", "a/b/two.txt"]);
+    expect(await store.list("nothing/")).toEqual([]);
+    expect((await store.list("a/o")).map((f) => f.key)).toEqual(["a/one.txt"]);
+  });
+  it(`${name}: refuses a key that climbs out, is empty or has a bad segment`, async () => {
+    const store = await make();
+    for (const key of ["../x.txt", "a/../b.txt", "/abs.txt", "a//b.txt", "a/b/", "", "a\\b.txt"]) await expect(store.put(key, bytes(1), { contentType: "text/plain" })).rejects.toMatchObject({ code: "STORAGE_BAD_KEY" });
+  });
+}
+export {
+  objectStoreContract
+};
+//# sourceMappingURL=testkit.js.map

package/dist/testkit.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/testkit.ts"],"sourcesContent":["import { expect, it } from \"vitest\";\n\nimport type { ObjectStore } from \"./port\";\n\nconst bytes = (...n: number[]) => new Uint8Array(n);\n\n/** What every `ObjectStore` adapter must do: the same behaviour behind the same port. `make` gives an empty store. */\nexport function objectStoreContract(name: string, make: () => ObjectStore | Promise<ObjectStore>) {\n  it(`${name}: stores a file and reads it back byte for byte`, async () => {\n    const store = await make();\n    await store.put(\"site/home/a.b1.png\", bytes(1, 2, 3, 255), { contentType: \"image/png\" });\n    const got = await store.get(\"site/home/a.b1.png\");\n    expect([...got!.bytes]).toEqual([1, 2, 3, 255]);\n    expect(got!.contentType).toBe(\"image/png\");\n    expect(await store.head(\"site/home/a.b1.png\")).toEqual({ key: \"site/home/a.b1.png\", size: 4 });\n  });\n\n  it(`${name}: answers null for a missing file, and deleting it twice is fine`, async () => {\n    const store = await make();\n    expect(await store.get(\"missing/file.txt\")).toBeNull();\n    expect(await store.head(\"missing/file.txt\")).toBeNull();\n    await store.put(\"x/y.txt\", bytes(1), { contentType: \"text/plain\" });\n    await store.delete(\"x/y.txt\");\n    await store.delete(\"x/y.txt\");\n    expect(await store.get(\"x/y.txt\")).toBeNull();\n  });\n\n  it(`${name}: overwrites a key`, async () => {\n    const store = await make();\n    await store.put(\"k/f.bin\", bytes(1), { contentType: \"application/octet-stream\" });\n    await store.put(\"k/f.bin\", bytes(9, 9), { contentType: \"application/octet-stream\" });\n    expect([...(await store.get(\"k/f.bin\"))!.bytes]).toEqual([9, 9]);\n  });\n\n  it(`${name}: lists the files under a prefix, directories flattened, in key order`, async () => {\n    const store = await make();\n    for (const key of [\"a/one.txt\", \"a/b/two.txt\", \"a/b/c/three.txt\", \"other/four.txt\", \"a-b/five.txt\"]) await store.put(key, bytes(7), { contentType: \"text/plain\" });\n    expect((await store.list(\"a/\")).map((f) => f.key)).toEqual([\"a/b/c/three.txt\", \"a/b/two.txt\", \"a/one.txt\"]);\n    expect((await store.list(\"a/b/\")).map((f) => f.key)).toEqual([\"a/b/c/three.txt\", \"a/b/two.txt\"]);\n    expect((await store.list(\"nothing/\"))).toEqual([]);\n    expect((await store.list(\"a/o\")).map((f) => f.key)).toEqual([\"a/one.txt\"]);\n  });\n\n  it(`${name}: refuses a key that climbs out, is empty or has a bad segment`, async () => {\n    const store = await make();\n    for (const key of [\"../x.txt\", \"a/../b.txt\", \"/abs.txt\", \"a//b.txt\", \"a/b/\", \"\", \"a\\\\b.txt\"]) await expect(store.put(key, bytes(1), { contentType: \"text/plain\" })).rejects.toMatchObject({ code: \"STORAGE_BAD_KEY\" });\n  });\n}\n"],"mappings":";AAAA,SAAS,QAAQ,UAAU;AAI3B,IAAM,QAAQ,IAAI,MAAgB,IAAI,WAAW,CAAC;AAG3C,SAAS,oBAAoB,MAAc,MAAgD;AAChG,KAAG,GAAG,IAAI,mDAAmD,YAAY;AACvE,UAAM,QAAQ,MAAM,KAAK;AACzB,UAAM,MAAM,IAAI,sBAAsB,MAAM,GAAG,GAAG,GAAG,GAAG,GAAG,EAAE,aAAa,YAAY,CAAC;AACvF,UAAM,MAAM,MAAM,MAAM,IAAI,oBAAoB;AAChD,WAAO,CAAC,GAAG,IAAK,KAAK,CAAC,EAAE,QAAQ,CAAC,GAAG,GAAG,GAAG,GAAG,CAAC;AAC9C,WAAO,IAAK,WAAW,EAAE,KAAK,WAAW;AACzC,WAAO,MAAM,MAAM,KAAK,oBAAoB,CAAC,EAAE,QAAQ,EAAE,KAAK,sBAAsB,MAAM,EAAE,CAAC;AAAA,EAC/F,CAAC;AAED,KAAG,GAAG,IAAI,oEAAoE,YAAY;AACxF,UAAM,QAAQ,MAAM,KAAK;AACzB,WAAO,MAAM,MAAM,IAAI,kBAAkB,CAAC,EAAE,SAAS;AACrD,WAAO,MAAM,MAAM,KAAK,kBAAkB,CAAC,EAAE,SAAS;AACtD,UAAM,MAAM,IAAI,WAAW,MAAM,CAAC,GAAG,EAAE,aAAa,aAAa,CAAC;AAClE,UAAM,MAAM,OAAO,SAAS;AAC5B,UAAM,MAAM,OAAO,SAAS;AAC5B,WAAO,MAAM,MAAM,IAAI,SAAS,CAAC,EAAE,SAAS;AAAA,EAC9C,CAAC;AAED,KAAG,GAAG,IAAI,sBAAsB,YAAY;AAC1C,UAAM,QAAQ,MAAM,KAAK;AACzB,UAAM,MAAM,IAAI,WAAW,MAAM,CAAC,GAAG,EAAE,aAAa,2BAA2B,CAAC;AAChF,UAAM,MAAM,IAAI,WAAW,MAAM,GAAG,CAAC,GAAG,EAAE,aAAa,2BAA2B,CAAC;AACnF,WAAO,CAAC,IAAI,MAAM,MAAM,IAAI,SAAS,GAAI,KAAK,CAAC,EAAE,QAAQ,CAAC,GAAG,CAAC,CAAC;AAAA,EACjE,CAAC;AAED,KAAG,GAAG,IAAI,yEAAyE,YAAY;AAC7F,UAAM,QAAQ,MAAM,KAAK;AACzB,eAAW,OAAO,CAAC,aAAa,eAAe,mBAAmB,kBAAkB,cAAc,EAAG,OAAM,MAAM,IAAI,KAAK,MAAM,CAAC,GAAG,EAAE,aAAa,aAAa,CAAC;AACjK,YAAQ,MAAM,MAAM,KAAK,IAAI,GAAG,IAAI,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE,QAAQ,CAAC,mBAAmB,eAAe,WAAW,CAAC;AAC1G,YAAQ,MAAM,MAAM,KAAK,MAAM,GAAG,IAAI,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE,QAAQ,CAAC,mBAAmB,aAAa,CAAC;AAC/F,WAAQ,MAAM,MAAM,KAAK,UAAU,CAAE,EAAE,QAAQ,CAAC,CAAC;AACjD,YAAQ,MAAM,MAAM,KAAK,KAAK,GAAG,IAAI,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE,QAAQ,CAAC,WAAW,CAAC;AAAA,EAC3E,CAAC;AAED,KAAG,GAAG,IAAI,kEAAkE,YAAY;AACtF,UAAM,QAAQ,MAAM,KAAK;AACzB,eAAW,OAAO,CAAC,YAAY,cAAc,YAAY,YAAY,QAAQ,IAAI,UAAU,EAAG,OAAM,OAAO,MAAM,IAAI,KAAK,MAAM,CAAC,GAAG,EAAE,aAAa,aAAa,CAAC,CAAC,EAAE,QAAQ,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAAA,EACvN,CAAC;AACH;","names":[]}