@geekmidas/constructs 7.0.1 → 10.0.0-alpha.0

package/dist/file-server.cjs

@@ -0,0 +1,154 @@
+const require_chunk = require('./chunk-DWy1uDak.cjs');
+const __geekmidas_manifest = require_chunk.__toESM(require("@geekmidas/manifest"));
+const __geekmidas_storage = require_chunk.__toESM(require("@geekmidas/storage"));
+
+//#region src/file-server.ts
+/** A key was asked to be served unsigned, and no open pattern admits it. */
+var NotOpen = class extends Error {
+	constructor(key, open) {
+		super(`'${key}' is not served without a signature. ` + (open.length ? `Open paths: ${open.join(", ")}. Use signedUrl() for anything else.` : "This file server declares no open paths, so every object needs signedUrl()."));
+		this.key = key;
+		this.open = open;
+		this.name = "NotOpen";
+	}
+};
+var FileServer = class {
+	id;
+	service;
+	/** The id of the surface node, as opposed to the bucket's. */
+	surfaceId;
+	open;
+	/**
+	* Declared once and read by both `declare()` and `connect()`, so the keys the
+	* target publishes and the keys the client reads cannot drift.
+	*/
+	keys;
+	constructor(id, options = {}) {
+		this.options = options;
+		const canonical = (0, __geekmidas_manifest.canonicalId)(id);
+		this.id = canonical;
+		this.open = options.open ?? [];
+		const originId = options.origin?.id ?? canonical;
+		this.surfaceId = `${canonical}Server`;
+		this.keys = {
+			origin: (0, __geekmidas_manifest.provideKey)(originId, "url"),
+			server: (0, __geekmidas_manifest.provideKey)(this.surfaceId, "url")
+		};
+		this.service = {
+			serviceName: (0, __geekmidas_manifest.serviceKey)(canonical),
+			register: (registerOptions) => this.connect(registerOptions)
+		};
+	}
+	/**
+	* The served surface, as something an edge can point at.
+	*
+	* Depending on the `FileServer` itself points at the **bucket** — its
+	* canonical node — which is right for a handler: it presigns and writes. But
+	* a bucket's URL is never public, so a site depending on it gets nothing
+	* inlined, which is correct and also useless.
+	*
+	* This is the other half: `.dependsOn([uploads.server])` points at the
+	* surface, whose address *is* public, and is what puts
+	* `VITE_UPLOADS_SERVER_URL` in a bundle. The same accessor shape
+	* `database.reader()` uses, and for the same reason — one construct owning
+	* two addresses needs a way to name the second.
+	*/
+	get server() {
+		const surface = this.declare().find((declaration) => declaration.id === this.surfaceId);
+		return {
+			id: this.surfaceId,
+			declare: () => surface ? [surface] : []
+		};
+	}
+	/**
+	* The bucket and the surface over it — or just the surface, when the bucket
+	* was declared elsewhere.
+	*
+	* The surface names its origin through `of`, which is what makes the
+	* reference check work: an origin resolving to nothing is a build failure,
+	* the same guarantee `assertDerivations` already gives a reader and a schema
+	* tenant.
+	*/
+	declare() {
+		const origin = this.options.origin;
+		const surface = {
+			kind: "file-server",
+			id: this.surfaceId,
+			of: origin?.id ?? this.id,
+			...this.open.length ? { open: this.open } : {},
+			provides: [this.keys.server]
+		};
+		if (origin) return [surface];
+		return [{
+			kind: "objects",
+			id: this.id,
+			provides: [this.keys.origin],
+			...this.options.versioned ? { versioned: true } : {}
+		}, surface];
+	}
+	/**
+	* The bucket's client, with the serving half added.
+	*
+	* Both addresses are read here, which is also how the environment reaches a
+	* handler: the sniffer records what this reads, so `.dependsOn([uploads])`
+	* carries the bucket URL and the server URL without either being written
+	* down beside the handler.
+	*/
+	async connect(options) {
+		const { origin, server } = options.envParser.create((get) => ({
+			origin: get(this.keys.origin).string(),
+			server: get(this.keys.server).string()
+		})).parse();
+		const storage = (0, __geekmidas_storage.createStorageClient)(origin);
+		const base = server.replace(/\/+$/, "");
+		const serve = (key) => {
+			if (!this.serves(key)) throw new NotOpen(key, this.open);
+			return `${base}/${key.replace(/^\/+/, "")}`;
+		};
+		return Object.assign(Object.create(storage), {
+			url: serve,
+			openUrl: serve,
+			signedUrl: (key, expiresIn) => storage.getDownloadURL({ path: key }, expiresIn)
+		});
+	}
+	/**
+	* Whether an open pattern admits a key.
+	*
+	* The runtime half of {@link Served}, and stricter than it: here a single
+	* star stops at a segment boundary and a double star does not, which is the
+	* distinction a template-literal type cannot draw and the infrastructure
+	* does.
+	*/
+	serves(key) {
+		return this.open.some((pattern) => globToRegExp(pattern).test(key));
+	}
+};
+/**
+* One open pattern as an anchored expression.
+*
+* A double star crosses `/`; a single star does not. Both are consumed in one
+* left-to-right pass rather than by substitution, so a pattern cannot be
+* rewritten into a placeholder that a later pass mistakes for literal text.
+*/
+function globToRegExp(pattern) {
+	let source = "";
+	for (let index = 0; index < pattern.length; index++) {
+		const character = pattern[index];
+		if (character !== "*") {
+			source += character?.replace(/[.+^${}()|[\]\\?]/, "\\$&") ?? "";
+			continue;
+		}
+		if (pattern[index + 1] === "*") {
+			source += ".*";
+			index++;
+			continue;
+		}
+		source += "[^/]*";
+	}
+	return new RegExp(`^${source}$`);
+}
+
+//#endregion
+exports.FileServer = FileServer;
+exports.NotOpen = NotOpen;
+//# sourceMappingURL=file-server.cjs.map

package/dist/file-server.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"file-server.cjs","names":["key: string","open: readonly string[]","id: ConstructName<TName>","options: FileServerOptions<TOpen>","surface: Declaration","options: ServiceRegisterOptions","expiresIn?: number","pattern: string"],"sources":["../src/file-server.ts"],"sourcesContent":["/**\n * `FileServer` — a domain that serves a bucket's objects.\n *\n * `ObjectStorage` is the bucket: it writes, it presigns, and its URL is never\n * public. Serving those objects on a domain is a different thing, and it is a\n * construct of its own rather than a flag on the bucket — see\n * `docs/design/constructs-paradigm.md`, \"Why a separate construct, and what it\n * costs\", for the comparison that rules the other two shapes out.\n *\n * ```ts\n * export const uploads = new FileServer('Uploads', { open: ['brand/**'] });\n *\n * uploads.getUploadURL({ path, contentType })  // an S3 presign at the bucket\n * uploads.url('brand/logo.png')                // open path — no signature\n * uploads.signedUrl('invoices/7.pdf')          // one object, one recipient\n * ```\n *\n * **One construct, one client, both halves.** How a file lands in the bucket is\n * the same whether or not it is served, so splitting the upload half from the\n * serving half would be ceremony rather than safety. The client is a *superset*\n * of `StorageClient`, made literal in the type, so anything taking\n * `services.uploads` keeps compiling when the construct behind it grows a\n * serving half.\n *\n * **The id names the bucket, not the surface.** This is the detail that has to\n * be right before anything ships, because getting it backwards is destructive:\n * the migration people actually perform is serving a bucket they already have,\n * and naming the bucket after the construct makes that edit *add* a node rather\n * than rename the one holding the data.\n */\n\nimport {\n\ttype ConstructName,\n\tcanonicalId,\n\ttype Declaration,\n\tprovideKey,\n\tserviceKey,\n} from '@geekmidas/manifest';\nimport type { Service, ServiceRegisterOptions } from '@geekmidas/services';\nimport { createStorageClient, type StorageClient } from '@geekmidas/storage';\nimport type { Construct, Declarable } from './construct-interface';\n\n/**\n * A key an open pattern admits.\n *\n * The same template-literal trick `ConstructName` uses, so `open` is checked at\n * the call site rather than only at the edge:\n *\n * ```ts\n * files.url('brand/logo.png')       // ok\n * files.url(`avatars/${id}.png`)    // ok — a template literal still matches\n * files.url('invoices/7.pdf')       // not assignable — never served unsigned\n * ```\n *\n * A single star and a double star resolve to the same type, stated rather than\n * discovered: a template literal cannot exclude `/`, so this is a prefix-and-\n * suffix guard while the *exact* pattern is enforced by the bucket policy, by\n * the cache behaviour, and by this construct's own runtime check. The type says\n * plausibly open; the infrastructure says definitely.\n */\nexport type Served<P extends string> = P extends `${infer Head}**`\n\t? `${Head}${string}`\n\t: P extends `${infer Head}*${infer Tail}`\n\t\t? `${Head}${string}${Tail}`\n\t\t: P;\n\n/** What consuming a file server hands you: a bucket client that also serves. */\nexport interface FileServerClient<TOpen extends string = never>\n\textends StorageClient {\n\t/**\n\t * The unsigned address of an open object.\n\t *\n\t * Compile-checked against the declared patterns, *and* checked again at\n\t * runtime — a JavaScript caller gets no compiler, and minting an unsigned\n\t * URL for a private object is a leak rather than a mistake.\n\t *\n\t * @throws {NotOpen} when the key matches no declared pattern.\n\t */\n\turl(key: Served<TOpen>): string;\n\n\t/**\n\t * The same thing for a key the compiler cannot see.\n\t *\n\t * A fully dynamic key does not type, which is correct and is also the case\n\t * people will hit — so the escape hatch is a named method rather than a\n\t * cast, and it runs the *same* runtime check rather than being a way around\n\t * it.\n\t *\n\t * @throws {NotOpen} when the key matches no declared pattern.\n\t */\n\topenUrl(key: string): string;\n\n\t/**\n\t * A signed address for one object and one recipient.\n\t *\n\t * Today this is an **S3 presign at the bucket**, which is what works\n\t * unchanged against MinIO locally and against S3 deployed. It is deliberately\n\t * not described as a CDN URL: CloudFront signing is a different mechanism,\n\t * with different keys, against a different host, and it needs key material\n\t * this construct does not yet declare.\n\t *\n\t * @param expiresIn - minutes, matching `getUploadURL`.\n\t */\n\tsignedUrl(key: string, expiresIn?: number): Promise<string>;\n}\n\nexport interface FileServerOptions<TOpen extends string = never> {\n\t/**\n\t * Paths served without a signature. Everything else needs one.\n\t *\n\t * Private by default: a bucket where forgetting a flag publishes user\n\t * uploads is the wrong default, so this is an exception list, and listing it\n\t * in code means exactly one set of paths is unauthenticated and it is\n\t * reviewable in a diff.\n\t *\n\t * Uploading is deliberately *not* restricted to these. Writing to a path\n\t * that happens to be open is ordinary; the only asymmetry worth enforcing is\n\t * that you cannot hand out an unsigned URL for something the server would\n\t * refuse to serve unsigned.\n\t */\n\topen?: readonly TOpen[];\n\t/** Keep previous versions of an object. */\n\tversioned?: boolean;\n\t/**\n\t * A bucket declared elsewhere, instead of one of this server's own.\n\t *\n\t * `new FileServer('Uploads')` declares both nodes; this fronts a bucket that\n\t * already exists, which is also how the two edges come back when you want\n\t * them separately — a handler depending on the bucket writes, a handler\n\t * depending on the server mints URLs.\n\t */\n\torigin?: Declarable;\n}\n\n/** A key was asked to be served unsigned, and no open pattern admits it. */\nexport class NotOpen extends Error {\n\tconstructor(\n\t\treadonly key: string,\n\t\treadonly open: readonly string[],\n\t) {\n\t\tsuper(\n\t\t\t`'${key}' is not served without a signature. ` +\n\t\t\t\t(open.length\n\t\t\t\t\t? `Open paths: ${open.join(', ')}. Use signedUrl() for anything else.`\n\t\t\t\t\t: 'This file server declares no open paths, so every object needs signedUrl().'),\n\t\t);\n\t\tthis.name = 'NotOpen';\n\t}\n}\n\nexport class FileServer<\n\tTName extends string = string,\n\tTOpen extends string = never,\n> implements Construct<TName, FileServerClient<TOpen>>\n{\n\treadonly id: TName;\n\treadonly service: Service<Uncapitalize<TName>, FileServerClient<TOpen>>;\n\n\t/** The id of the surface node, as opposed to the bucket's. */\n\treadonly surfaceId: string;\n\n\tprivate readonly open: readonly string[];\n\n\t/**\n\t * Declared once and read by both `declare()` and `connect()`, so the keys the\n\t * target publishes and the keys the client reads cannot drift.\n\t */\n\tprivate readonly keys: { origin: string; server: string };\n\n\tconstructor(\n\t\tid: ConstructName<TName>,\n\t\tprivate readonly options: FileServerOptions<TOpen> = {},\n\t) {\n\t\tconst canonical = canonicalId(id as string);\n\n\t\tthis.id = canonical as TName;\n\t\tthis.open = options.open ?? [];\n\n\t\t// The surface takes the suffix and the bucket keeps the plain id, which\n\t\t// is what makes \"serve a bucket I already have\" an edit that adds a node\n\t\t// instead of renaming the one holding the data.\n\t\tconst originId = options.origin?.id ?? canonical;\n\t\tthis.surfaceId = `${canonical}Server`;\n\n\t\tthis.keys = {\n\t\t\torigin: provideKey(originId, 'url'),\n\t\t\tserver: provideKey(this.surfaceId, 'url'),\n\t\t};\n\n\t\t// A field, not a getter: consumers cache services by object identity.\n\t\tthis.service = {\n\t\t\tserviceName: serviceKey(canonical) as Uncapitalize<TName>,\n\t\t\tregister: (registerOptions) => this.connect(registerOptions),\n\t\t};\n\t}\n\n\t/**\n\t * The served surface, as something an edge can point at.\n\t *\n\t * Depending on the `FileServer` itself points at the **bucket** — its\n\t * canonical node — which is right for a handler: it presigns and writes. But\n\t * a bucket's URL is never public, so a site depending on it gets nothing\n\t * inlined, which is correct and also useless.\n\t *\n\t * This is the other half: `.dependsOn([uploads.server])` points at the\n\t * surface, whose address *is* public, and is what puts\n\t * `VITE_UPLOADS_SERVER_URL` in a bundle. The same accessor shape\n\t * `database.reader()` uses, and for the same reason — one construct owning\n\t * two addresses needs a way to name the second.\n\t */\n\tget server(): Declarable {\n\t\tconst surface = this.declare().find(\n\t\t\t(declaration) => declaration.id === this.surfaceId,\n\t\t);\n\n\t\treturn {\n\t\t\tid: this.surfaceId,\n\t\t\tdeclare: () => (surface ? [surface] : []),\n\t\t};\n\t}\n\n\t/**\n\t * The bucket and the surface over it — or just the surface, when the bucket\n\t * was declared elsewhere.\n\t *\n\t * The surface names its origin through `of`, which is what makes the\n\t * reference check work: an origin resolving to nothing is a build failure,\n\t * the same guarantee `assertDerivations` already gives a reader and a schema\n\t * tenant.\n\t */\n\tdeclare(): Declaration[] {\n\t\tconst origin = this.options.origin;\n\n\t\tconst surface: Declaration = {\n\t\t\tkind: 'file-server',\n\t\t\tid: this.surfaceId,\n\t\t\tof: origin?.id ?? this.id,\n\t\t\t...(this.open.length ? { open: this.open } : {}),\n\t\t\tprovides: [this.keys.server],\n\t\t};\n\n\t\t// A vended bucket is declared here; a given one already declares itself,\n\t\t// and declaring it twice is the duplication the whole model removes.\n\t\tif (origin) return [surface];\n\n\t\treturn [\n\t\t\t{\n\t\t\t\tkind: 'objects',\n\t\t\t\tid: this.id,\n\t\t\t\tprovides: [this.keys.origin],\n\t\t\t\t...(this.options.versioned ? { versioned: true } : {}),\n\t\t\t},\n\t\t\tsurface,\n\t\t];\n\t}\n\n\t/**\n\t * The bucket's client, with the serving half added.\n\t *\n\t * Both addresses are read here, which is also how the environment reaches a\n\t * handler: the sniffer records what this reads, so `.dependsOn([uploads])`\n\t * carries the bucket URL and the server URL without either being written\n\t * down beside the handler.\n\t */\n\tprivate async connect(\n\t\toptions: ServiceRegisterOptions,\n\t): Promise<FileServerClient<TOpen>> {\n\t\tconst { origin, server } = options.envParser\n\t\t\t.create((get) => ({\n\t\t\t\torigin: get(this.keys.origin).string(),\n\t\t\t\tserver: get(this.keys.server).string(),\n\t\t\t}))\n\t\t\t.parse();\n\n\t\tconst storage = createStorageClient(origin);\n\t\tconst base = server.replace(/\\/+$/, '');\n\n\t\tconst serve = (key: string): string => {\n\t\t\tif (!this.serves(key)) throw new NotOpen(key, this.open);\n\n\t\t\treturn `${base}/${key.replace(/^\\/+/, '')}`;\n\t\t};\n\n\t\t// Delegating rather than copying: the bucket half is whatever the driver\n\t\t// produced, including anything it grows later, and only the serving half\n\t\t// is added on top.\n\t\treturn Object.assign(Object.create(storage) as StorageClient, {\n\t\t\turl: serve as (key: Served<TOpen>) => string,\n\t\t\topenUrl: serve,\n\t\t\tsignedUrl: (key: string, expiresIn?: number) =>\n\t\t\t\tstorage.getDownloadURL({ path: key } as never, expiresIn),\n\t\t}) as FileServerClient<TOpen>;\n\t}\n\n\t/**\n\t * Whether an open pattern admits a key.\n\t *\n\t * The runtime half of {@link Served}, and stricter than it: here a single\n\t * star stops at a segment boundary and a double star does not, which is the\n\t * distinction a template-literal type cannot draw and the infrastructure\n\t * does.\n\t */\n\tprivate serves(key: string): boolean {\n\t\treturn this.open.some((pattern) => globToRegExp(pattern).test(key));\n\t}\n}\n\n/**\n * One open pattern as an anchored expression.\n *\n * A double star crosses `/`; a single star does not. Both are consumed in one\n * left-to-right pass rather than by substitution, so a pattern cannot be\n * rewritten into a placeholder that a later pass mistakes for literal text.\n */\nfunction globToRegExp(pattern: string): RegExp {\n\tlet source = '';\n\n\tfor (let index = 0; index < pattern.length; index++) {\n\t\tconst character = pattern[index];\n\n\t\tif (character !== '*') {\n\t\t\tsource += character?.replace(/[.+^${}()|[\\]\\\\?]/, '\\\\$&') ?? '';\n\t\t\tcontinue;\n\t\t}\n\n\t\tif (pattern[index + 1] === '*') {\n\t\t\tsource += '.*';\n\t\t\tindex++;\n\t\t\tcontinue;\n\t\t}\n\n\t\tsource += '[^/]*';\n\t}\n\n\treturn new RegExp(`^${source}$`);\n}\n"],"mappings":"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"}

package/dist/file-server.d.cts

@@ -0,0 +1,156 @@
+import { Construct, Declarable } from "./construct-interface-D2nNkHUN.cjs";
+import { Service } from "@geekmidas/services";
+import { ConstructName, Declaration } from "@geekmidas/manifest";
+import { StorageClient } from "@geekmidas/storage";
+
+//#region src/file-server.d.ts
+
+/**
+ * A key an open pattern admits.
+ *
+ * The same template-literal trick `ConstructName` uses, so `open` is checked at
+ * the call site rather than only at the edge:
+ *
+ * ```ts
+ * files.url('brand/logo.png')       // ok
+ * files.url(`avatars/${id}.png`)    // ok — a template literal still matches
+ * files.url('invoices/7.pdf')       // not assignable — never served unsigned
+ * ```
+ *
+ * A single star and a double star resolve to the same type, stated rather than
+ * discovered: a template literal cannot exclude `/`, so this is a prefix-and-
+ * suffix guard while the *exact* pattern is enforced by the bucket policy, by
+ * the cache behaviour, and by this construct's own runtime check. The type says
+ * plausibly open; the infrastructure says definitely.
+ */
+type Served<P extends string> = P extends `${infer Head}**` ? `${Head}${string}` : P extends `${infer Head}*${infer Tail}` ? `${Head}${string}${Tail}` : P;
+/** What consuming a file server hands you: a bucket client that also serves. */
+interface FileServerClient<TOpen extends string = never> extends StorageClient {
+  /**
+   * The unsigned address of an open object.
+   *
+   * Compile-checked against the declared patterns, *and* checked again at
+   * runtime — a JavaScript caller gets no compiler, and minting an unsigned
+   * URL for a private object is a leak rather than a mistake.
+   *
+   * @throws {NotOpen} when the key matches no declared pattern.
+   */
+  url(key: Served<TOpen>): string;
+  /**
+   * The same thing for a key the compiler cannot see.
+   *
+   * A fully dynamic key does not type, which is correct and is also the case
+   * people will hit — so the escape hatch is a named method rather than a
+   * cast, and it runs the *same* runtime check rather than being a way around
+   * it.
+   *
+   * @throws {NotOpen} when the key matches no declared pattern.
+   */
+  openUrl(key: string): string;
+  /**
+   * A signed address for one object and one recipient.
+   *
+   * Today this is an **S3 presign at the bucket**, which is what works
+   * unchanged against MinIO locally and against S3 deployed. It is deliberately
+   * not described as a CDN URL: CloudFront signing is a different mechanism,
+   * with different keys, against a different host, and it needs key material
+   * this construct does not yet declare.
+   *
+   * @param expiresIn - minutes, matching `getUploadURL`.
+   */
+  signedUrl(key: string, expiresIn?: number): Promise<string>;
+}
+interface FileServerOptions<TOpen extends string = never> {
+  /**
+   * Paths served without a signature. Everything else needs one.
+   *
+   * Private by default: a bucket where forgetting a flag publishes user
+   * uploads is the wrong default, so this is an exception list, and listing it
+   * in code means exactly one set of paths is unauthenticated and it is
+   * reviewable in a diff.
+   *
+   * Uploading is deliberately *not* restricted to these. Writing to a path
+   * that happens to be open is ordinary; the only asymmetry worth enforcing is
+   * that you cannot hand out an unsigned URL for something the server would
+   * refuse to serve unsigned.
+   */
+  open?: readonly TOpen[];
+  /** Keep previous versions of an object. */
+  versioned?: boolean;
+  /**
+   * A bucket declared elsewhere, instead of one of this server's own.
+   *
+   * `new FileServer('Uploads')` declares both nodes; this fronts a bucket that
+   * already exists, which is also how the two edges come back when you want
+   * them separately — a handler depending on the bucket writes, a handler
+   * depending on the server mints URLs.
+   */
+  origin?: Declarable;
+}
+/** A key was asked to be served unsigned, and no open pattern admits it. */
+declare class NotOpen extends Error {
+  readonly key: string;
+  readonly open: readonly string[];
+  constructor(key: string, open: readonly string[]);
+}
+declare class FileServer<TName extends string = string, TOpen extends string = never> implements Construct<TName, FileServerClient<TOpen>> {
+  private readonly options;
+  readonly id: TName;
+  readonly service: Service<Uncapitalize<TName>, FileServerClient<TOpen>>;
+  /** The id of the surface node, as opposed to the bucket's. */
+  readonly surfaceId: string;
+  private readonly open;
+  /**
+   * Declared once and read by both `declare()` and `connect()`, so the keys the
+   * target publishes and the keys the client reads cannot drift.
+   */
+  private readonly keys;
+  constructor(id: ConstructName<TName>, options?: FileServerOptions<TOpen>);
+  /**
+   * The served surface, as something an edge can point at.
+   *
+   * Depending on the `FileServer` itself points at the **bucket** — its
+   * canonical node — which is right for a handler: it presigns and writes. But
+   * a bucket's URL is never public, so a site depending on it gets nothing
+   * inlined, which is correct and also useless.
+   *
+   * This is the other half: `.dependsOn([uploads.server])` points at the
+   * surface, whose address *is* public, and is what puts
+   * `VITE_UPLOADS_SERVER_URL` in a bundle. The same accessor shape
+   * `database.reader()` uses, and for the same reason — one construct owning
+   * two addresses needs a way to name the second.
+   */
+  get server(): Declarable;
+  /**
+   * The bucket and the surface over it — or just the surface, when the bucket
+   * was declared elsewhere.
+   *
+   * The surface names its origin through `of`, which is what makes the
+   * reference check work: an origin resolving to nothing is a build failure,
+   * the same guarantee `assertDerivations` already gives a reader and a schema
+   * tenant.
+   */
+  declare(): Declaration[];
+  /**
+   * The bucket's client, with the serving half added.
+   *
+   * Both addresses are read here, which is also how the environment reaches a
+   * handler: the sniffer records what this reads, so `.dependsOn([uploads])`
+   * carries the bucket URL and the server URL without either being written
+   * down beside the handler.
+   */
+  private connect;
+  /**
+   * Whether an open pattern admits a key.
+   *
+   * The runtime half of {@link Served}, and stricter than it: here a single
+   * star stops at a segment boundary and a double star does not, which is the
+   * distinction a template-literal type cannot draw and the infrastructure
+   * does.
+   */
+  private serves;
+}
+//# sourceMappingURL=file-server.d.ts.map
+//#endregion
+export { FileServer, FileServerClient, FileServerOptions, NotOpen, Served };
+//# sourceMappingURL=file-server.d.cts.map

package/dist/file-server.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"file-server.d.cts","names":[],"sources":["../src/file-server.ts"],"sourcesContent":[],"mappings":";;;;;;;;;;;;;;;;;;;AAyJsB;;;;;;KA7FV,2BAA2B,iCACjC,kBACH,6CACI,gBAAgB,SACnB;;UAGa,uDACR;;;;;;;;;;WAUC,OAAO;;;;;;;;;;;;;;;;;;;;;;;8CAyB4B;;UAG5B;;;;;;;;;;;;;;kBAcA;;;;;;;;;;;WAWP;;;cAIG,OAAA,SAAgB,KAAK;;;;;cAerB,mFAGA,UAAU,OAAO,iBAAiB;;eAEjC;oBACK,QAAQ,aAAa,QAAQ,iBAAiB;;;;;;;;;kBAc3D,cAAc,kBACQ,kBAAkB;;;;;;;;;;;;;;;gBAuC/B;;;;;;;;;;aAoBH"}

package/dist/file-server.d.mts

@@ -0,0 +1,156 @@
+import { Construct, Declarable } from "./construct-interface-BqwRNYA2.mjs";
+import { ConstructName, Declaration } from "@geekmidas/manifest";
+import { StorageClient } from "@geekmidas/storage";
+import { Service } from "@geekmidas/services";
+
+//#region src/file-server.d.ts
+
+/**
+ * A key an open pattern admits.
+ *
+ * The same template-literal trick `ConstructName` uses, so `open` is checked at
+ * the call site rather than only at the edge:
+ *
+ * ```ts
+ * files.url('brand/logo.png')       // ok
+ * files.url(`avatars/${id}.png`)    // ok — a template literal still matches
+ * files.url('invoices/7.pdf')       // not assignable — never served unsigned
+ * ```
+ *
+ * A single star and a double star resolve to the same type, stated rather than
+ * discovered: a template literal cannot exclude `/`, so this is a prefix-and-
+ * suffix guard while the *exact* pattern is enforced by the bucket policy, by
+ * the cache behaviour, and by this construct's own runtime check. The type says
+ * plausibly open; the infrastructure says definitely.
+ */
+type Served<P extends string> = P extends `${infer Head}**` ? `${Head}${string}` : P extends `${infer Head}*${infer Tail}` ? `${Head}${string}${Tail}` : P;
+/** What consuming a file server hands you: a bucket client that also serves. */
+interface FileServerClient<TOpen extends string = never> extends StorageClient {
+  /**
+   * The unsigned address of an open object.
+   *
+   * Compile-checked against the declared patterns, *and* checked again at
+   * runtime — a JavaScript caller gets no compiler, and minting an unsigned
+   * URL for a private object is a leak rather than a mistake.
+   *
+   * @throws {NotOpen} when the key matches no declared pattern.
+   */
+  url(key: Served<TOpen>): string;
+  /**
+   * The same thing for a key the compiler cannot see.
+   *
+   * A fully dynamic key does not type, which is correct and is also the case
+   * people will hit — so the escape hatch is a named method rather than a
+   * cast, and it runs the *same* runtime check rather than being a way around
+   * it.
+   *
+   * @throws {NotOpen} when the key matches no declared pattern.
+   */
+  openUrl(key: string): string;
+  /**
+   * A signed address for one object and one recipient.
+   *
+   * Today this is an **S3 presign at the bucket**, which is what works
+   * unchanged against MinIO locally and against S3 deployed. It is deliberately
+   * not described as a CDN URL: CloudFront signing is a different mechanism,
+   * with different keys, against a different host, and it needs key material
+   * this construct does not yet declare.
+   *
+   * @param expiresIn - minutes, matching `getUploadURL`.
+   */
+  signedUrl(key: string, expiresIn?: number): Promise<string>;
+}
+interface FileServerOptions<TOpen extends string = never> {
+  /**
+   * Paths served without a signature. Everything else needs one.
+   *
+   * Private by default: a bucket where forgetting a flag publishes user
+   * uploads is the wrong default, so this is an exception list, and listing it
+   * in code means exactly one set of paths is unauthenticated and it is
+   * reviewable in a diff.
+   *
+   * Uploading is deliberately *not* restricted to these. Writing to a path
+   * that happens to be open is ordinary; the only asymmetry worth enforcing is
+   * that you cannot hand out an unsigned URL for something the server would
+   * refuse to serve unsigned.
+   */
+  open?: readonly TOpen[];
+  /** Keep previous versions of an object. */
+  versioned?: boolean;
+  /**
+   * A bucket declared elsewhere, instead of one of this server's own.
+   *
+   * `new FileServer('Uploads')` declares both nodes; this fronts a bucket that
+   * already exists, which is also how the two edges come back when you want
+   * them separately — a handler depending on the bucket writes, a handler
+   * depending on the server mints URLs.
+   */
+  origin?: Declarable;
+}
+/** A key was asked to be served unsigned, and no open pattern admits it. */
+declare class NotOpen extends Error {
+  readonly key: string;
+  readonly open: readonly string[];
+  constructor(key: string, open: readonly string[]);
+}
+declare class FileServer<TName extends string = string, TOpen extends string = never> implements Construct<TName, FileServerClient<TOpen>> {
+  private readonly options;
+  readonly id: TName;
+  readonly service: Service<Uncapitalize<TName>, FileServerClient<TOpen>>;
+  /** The id of the surface node, as opposed to the bucket's. */
+  readonly surfaceId: string;
+  private readonly open;
+  /**
+   * Declared once and read by both `declare()` and `connect()`, so the keys the
+   * target publishes and the keys the client reads cannot drift.
+   */
+  private readonly keys;
+  constructor(id: ConstructName<TName>, options?: FileServerOptions<TOpen>);
+  /**
+   * The served surface, as something an edge can point at.
+   *
+   * Depending on the `FileServer` itself points at the **bucket** — its
+   * canonical node — which is right for a handler: it presigns and writes. But
+   * a bucket's URL is never public, so a site depending on it gets nothing
+   * inlined, which is correct and also useless.
+   *
+   * This is the other half: `.dependsOn([uploads.server])` points at the
+   * surface, whose address *is* public, and is what puts
+   * `VITE_UPLOADS_SERVER_URL` in a bundle. The same accessor shape
+   * `database.reader()` uses, and for the same reason — one construct owning
+   * two addresses needs a way to name the second.
+   */
+  get server(): Declarable;
+  /**
+   * The bucket and the surface over it — or just the surface, when the bucket
+   * was declared elsewhere.
+   *
+   * The surface names its origin through `of`, which is what makes the
+   * reference check work: an origin resolving to nothing is a build failure,
+   * the same guarantee `assertDerivations` already gives a reader and a schema
+   * tenant.
+   */
+  declare(): Declaration[];
+  /**
+   * The bucket's client, with the serving half added.
+   *
+   * Both addresses are read here, which is also how the environment reaches a
+   * handler: the sniffer records what this reads, so `.dependsOn([uploads])`
+   * carries the bucket URL and the server URL without either being written
+   * down beside the handler.
+   */
+  private connect;
+  /**
+   * Whether an open pattern admits a key.
+   *
+   * The runtime half of {@link Served}, and stricter than it: here a single
+   * star stops at a segment boundary and a double star does not, which is the
+   * distinction a template-literal type cannot draw and the infrastructure
+   * does.
+   */
+  private serves;
+}
+//# sourceMappingURL=file-server.d.ts.map
+//#endregion
+export { FileServer, FileServerClient, FileServerOptions, NotOpen, Served };
+//# sourceMappingURL=file-server.d.mts.map

package/dist/file-server.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"file-server.d.mts","names":[],"sources":["../src/file-server.ts"],"sourcesContent":[],"mappings":";;;;;;;;;;;;;;;;;;;AAyJsB;;;;;;KA7FV,2BAA2B,iCACjC,kBACH,6CACI,gBAAgB,SACnB;;UAGa,uDACR;;;;;;;;;;WAUC,OAAO;;;;;;;;;;;;;;;;;;;;;;;8CAyB4B;;UAG5B;;;;;;;;;;;;;;kBAcA;;;;;;;;;;;WAWP;;;cAIG,OAAA,SAAgB,KAAK;;;;;cAerB,mFAGA,UAAU,OAAO,iBAAiB;;eAEjC;oBACK,QAAQ,aAAa,QAAQ,iBAAiB;;;;;;;;;kBAc3D,cAAc,kBACQ,kBAAkB;;;;;;;;;;;;;;;gBAuC/B;;;;;;;;;;aAoBH"}

package/dist/file-server.mjs

@@ -0,0 +1,152 @@
+import { canonicalId, provideKey, serviceKey } from "@geekmidas/manifest";
+import { createStorageClient } from "@geekmidas/storage";
+
+//#region src/file-server.ts
+/** A key was asked to be served unsigned, and no open pattern admits it. */
+var NotOpen = class extends Error {
+	constructor(key, open) {
+		super(`'${key}' is not served without a signature. ` + (open.length ? `Open paths: ${open.join(", ")}. Use signedUrl() for anything else.` : "This file server declares no open paths, so every object needs signedUrl()."));
+		this.key = key;
+		this.open = open;
+		this.name = "NotOpen";
+	}
+};
+var FileServer = class {
+	id;
+	service;
+	/** The id of the surface node, as opposed to the bucket's. */
+	surfaceId;
+	open;
+	/**
+	* Declared once and read by both `declare()` and `connect()`, so the keys the
+	* target publishes and the keys the client reads cannot drift.
+	*/
+	keys;
+	constructor(id, options = {}) {
+		this.options = options;
+		const canonical = canonicalId(id);
+		this.id = canonical;
+		this.open = options.open ?? [];
+		const originId = options.origin?.id ?? canonical;
+		this.surfaceId = `${canonical}Server`;
+		this.keys = {
+			origin: provideKey(originId, "url"),
+			server: provideKey(this.surfaceId, "url")
+		};
+		this.service = {
+			serviceName: serviceKey(canonical),
+			register: (registerOptions) => this.connect(registerOptions)
+		};
+	}
+	/**
+	* The served surface, as something an edge can point at.
+	*
+	* Depending on the `FileServer` itself points at the **bucket** — its
+	* canonical node — which is right for a handler: it presigns and writes. But
+	* a bucket's URL is never public, so a site depending on it gets nothing
+	* inlined, which is correct and also useless.
+	*
+	* This is the other half: `.dependsOn([uploads.server])` points at the
+	* surface, whose address *is* public, and is what puts
+	* `VITE_UPLOADS_SERVER_URL` in a bundle. The same accessor shape
+	* `database.reader()` uses, and for the same reason — one construct owning
+	* two addresses needs a way to name the second.
+	*/
+	get server() {
+		const surface = this.declare().find((declaration) => declaration.id === this.surfaceId);
+		return {
+			id: this.surfaceId,
+			declare: () => surface ? [surface] : []
+		};
+	}
+	/**
+	* The bucket and the surface over it — or just the surface, when the bucket
+	* was declared elsewhere.
+	*
+	* The surface names its origin through `of`, which is what makes the
+	* reference check work: an origin resolving to nothing is a build failure,
+	* the same guarantee `assertDerivations` already gives a reader and a schema
+	* tenant.
+	*/
+	declare() {
+		const origin = this.options.origin;
+		const surface = {
+			kind: "file-server",
+			id: this.surfaceId,
+			of: origin?.id ?? this.id,
+			...this.open.length ? { open: this.open } : {},
+			provides: [this.keys.server]
+		};
+		if (origin) return [surface];
+		return [{
+			kind: "objects",
+			id: this.id,
+			provides: [this.keys.origin],
+			...this.options.versioned ? { versioned: true } : {}
+		}, surface];
+	}
+	/**
+	* The bucket's client, with the serving half added.
+	*
+	* Both addresses are read here, which is also how the environment reaches a
+	* handler: the sniffer records what this reads, so `.dependsOn([uploads])`
+	* carries the bucket URL and the server URL without either being written
+	* down beside the handler.
+	*/
+	async connect(options) {
+		const { origin, server } = options.envParser.create((get) => ({
+			origin: get(this.keys.origin).string(),
+			server: get(this.keys.server).string()
+		})).parse();
+		const storage = createStorageClient(origin);
+		const base = server.replace(/\/+$/, "");
+		const serve = (key) => {
+			if (!this.serves(key)) throw new NotOpen(key, this.open);
+			return `${base}/${key.replace(/^\/+/, "")}`;
+		};
+		return Object.assign(Object.create(storage), {
+			url: serve,
+			openUrl: serve,
+			signedUrl: (key, expiresIn) => storage.getDownloadURL({ path: key }, expiresIn)
+		});
+	}
+	/**
+	* Whether an open pattern admits a key.
+	*
+	* The runtime half of {@link Served}, and stricter than it: here a single
+	* star stops at a segment boundary and a double star does not, which is the
+	* distinction a template-literal type cannot draw and the infrastructure
+	* does.
+	*/
+	serves(key) {
+		return this.open.some((pattern) => globToRegExp(pattern).test(key));
+	}
+};
+/**
+* One open pattern as an anchored expression.
+*
+* A double star crosses `/`; a single star does not. Both are consumed in one
+* left-to-right pass rather than by substitution, so a pattern cannot be
+* rewritten into a placeholder that a later pass mistakes for literal text.
+*/
+function globToRegExp(pattern) {
+	let source = "";
+	for (let index = 0; index < pattern.length; index++) {
+		const character = pattern[index];
+		if (character !== "*") {
+			source += character?.replace(/[.+^${}()|[\]\\?]/, "\\$&") ?? "";
+			continue;
+		}
+		if (pattern[index + 1] === "*") {
+			source += ".*";
+			index++;
+			continue;
+		}
+		source += "[^/]*";
+	}
+	return new RegExp(`^${source}$`);
+}
+
+//#endregion
+export { FileServer, NotOpen };
+//# sourceMappingURL=file-server.mjs.map