better-supabase 0.5.0 → 0.6.0

package/dist/blocks/api-keys/index.js

@@ -0,0 +1,334 @@
+import { n as dbError } from "../../errors-B11Duf73.js";
+import { t as temporal } from "../../temporal-required-BVvW7SYJ.js";
+import { a as ok, t as AsyncResult } from "../../result-DzUbqgdW.js";
+import { a as problemResponse } from "../../problem-BreOl8b8.js";
+import { a as withAuthMode, o as withJwtClaims, s as withUserClaims } from "../../claims-DDBQT6BK.js";
+import { n as rpcTransport, r as sqlTransport } from "../../block-transport-BLr-ZgLc.js";
+import { D as stringsOf, O as textOf, T as sha256Hex, h as optionalText, i as blockCall, m as optionalInstant, n as applyTemporal, u as instantArg, x as recordsOf, y as recordOf } from "../../block-helpers-DWHxHsEQ.js";
+import { defineComposite, defineMiddleware } from "@supabase/middleware";
+//#region src/blocks/api-keys/api-keys.ts
+const TOKEN = /^([a-z][a-z0-9]*)_([0-9a-f]{16})_([A-Za-z0-9_-]{32,})$/;
+const PREFIX = /^[a-z][a-z0-9]*$/;
+const ALPHABET = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789";
+const SECRET_LENGTH = 43;
+const CHECKSUM_LENGTH = 6;
+const CHECKED_TAIL = /^[A-Za-z0-9]{49}$/;
+const CRC_TABLE = (() => {
+	const table = /* @__PURE__ */ new Uint32Array(256);
+	for (let index = 0; index < 256; index += 1) {
+		let value = index;
+		for (let bit = 0; bit < 8; bit += 1) value = value & 1 ? 3988292384 ^ value >>> 1 : value >>> 1;
+		table[index] = value >>> 0;
+	}
+	return table;
+})();
+/**
+* The CRC-32 (IEEE 802.3) of `text` as 6 base62 characters: the checksum
+* GitHub-style tokens end in, so a secret
+* scanner or the server rejects a mistyped key without a lookup.
+*/
+function apiKeyChecksum(text) {
+	let crc = 4294967295;
+	for (let index = 0; index < text.length; index += 1) crc = (CRC_TABLE[(crc ^ (text.codePointAt(index) ?? 0)) & 255] ?? 0) ^ crc >>> 8;
+	let value = (crc ^ 4294967295) >>> 0;
+	let out = "";
+	for (let index = 0; index < CHECKSUM_LENGTH; index += 1) {
+		out = ALPHABET[value % 62] + out;
+		value = Math.floor(value / 62);
+	}
+	return out;
+}
+function base62Secret() {
+	let secret = "";
+	const bytes = /* @__PURE__ */ new Uint8Array(64);
+	while (secret.length < SECRET_LENGTH) {
+		crypto.getRandomValues(bytes);
+		for (const byte of bytes) if (byte < 248 && secret.length < SECRET_LENGTH) secret += ALPHABET[byte % 62];
+	}
+	return secret;
+}
+/**
+* Splits `<prefix>_<public id>_<secret><checksum>`: a 43-character base62
+* secret and the 6-character checksum of everything before it. A key from
+* before the checksum (`<prefix>_<public id>_<secret>`) still parses. A
+* checksum that doesn't match, or anything else (a JWT, say), is
+* `undefined`.
+*/
+function parseApiKey(token) {
+	const match = TOKEN.exec(token.trim());
+	if (!match) return void 0;
+	const prefix = match[1];
+	const publicId = match[2];
+	const tail = match[3];
+	if (CHECKED_TAIL.test(tail)) {
+		const secret = tail.slice(0, SECRET_LENGTH);
+		return tail.slice(SECRET_LENGTH) === apiKeyChecksum(`${prefix}_${publicId}_${secret}`) ? {
+			prefix,
+			publicId,
+			secret,
+			checksum: true
+		} : void 0;
+	}
+	return {
+		prefix,
+		publicId,
+		secret: tail,
+		checksum: false
+	};
+}
+function publicId() {
+	const bytes = crypto.getRandomValues(/* @__PURE__ */ new Uint8Array(8));
+	return Array.from(bytes, (byte) => byte.toString(16).padStart(2, "0")).join("");
+}
+const STATES = [
+	"active",
+	"grace",
+	"revoked",
+	"expired"
+];
+function stateOf(value, revokedAt, expiresAt) {
+	const known = STATES.find((state) => state === value);
+	if (known) return known;
+	const now = temporal().Now.instant();
+	const past = (at) => at !== void 0 && temporal().Instant.compare(at, now) <= 0;
+	if (past(revokedAt)) return "revoked";
+	if (past(expiresAt)) return "expired";
+	return revokedAt === void 0 ? "active" : "grace";
+}
+function apiKeyOf(value) {
+	const row = recordOf(value, "api key");
+	const organizationId = optionalText(row["organization_id"]);
+	const userId = optionalText(row["user_id"]);
+	const expiresAt = optionalInstant(row["expires_at"]);
+	const lastUsedAt = optionalInstant(row["last_used_at"]);
+	const revokedAt = optionalInstant(row["revoked_at"]);
+	const rotatedFrom = optionalText(row["rotated_from"]);
+	const createdBy = optionalText(row["created_by"]);
+	const successorId = optionalText(row["successor_id"]);
+	const rateLimit = row["rate_limit"];
+	return {
+		id: textOf(row["id"]),
+		...organizationId ? { organizationId } : {},
+		...userId ? { userId } : {},
+		name: textOf(row["name"]),
+		prefix: textOf(row["prefix"]),
+		publicId: textOf(row["public_id"]),
+		scopes: stringsOf(row["scopes"]),
+		...typeof rateLimit === "number" ? { rateLimit } : {},
+		...expiresAt ? { expiresAt } : {},
+		...lastUsedAt ? { lastUsedAt } : {},
+		...revokedAt ? { revokedAt } : {},
+		...rotatedFrom ? { rotatedFrom } : {},
+		...createdBy ? { createdBy } : {},
+		createdAt: optionalInstant(row["created_at"]) ?? temporal().Now.instant(),
+		state: stateOf(row["state"], revokedAt, expiresAt),
+		...successorId ? { successorId } : {}
+	};
+}
+function checkOf(value) {
+	const row = recordOf(value, "verify_api_key");
+	switch (row["status"]) {
+		case "ok": return {
+			status: "ok",
+			key: apiKeyOf(row["key"])
+		};
+		case "rate_limited": return {
+			status: "rate_limited",
+			retryAfter: Number(row["retry_after"] ?? 60)
+		};
+		default: return { status: "invalid" };
+	}
+}
+/**
+* API keys over the `api-keys` SQL module. Members create and rotate keys
+* with their own transport; `verify` (and `apiKeyResolver`) need one that
+* runs as the service role.
+*/
+function createApiKeys(options) {
+	applyTemporal(options);
+	const prefix = options.prefix ?? "bs";
+	if (!PREFIX.test(prefix)) throw new TypeError(`createApiKeys: prefix must be lowercase letters and digits, not "${prefix}"`);
+	const call = blockCall(options.transport, options.schema ?? "better_supabase");
+	const fresh = async () => {
+		const id = publicId();
+		const secret = base62Secret();
+		const key = `${prefix}_${id}_${secret}`;
+		return {
+			id,
+			token: `${key}${apiKeyChecksum(key)}`,
+			hash: await sha256Hex(secret)
+		};
+	};
+	return {
+		create: (input) => AsyncResult.from(async () => {
+			const { id, token, hash } = await fresh();
+			return call("create_api_key", {
+				name: input.name,
+				public_id: id,
+				secret_hash: hash,
+				tenant: input.organizationId ?? null,
+				personal: input.personal ?? false,
+				scopes: input.scopes ?? [],
+				expires_at: instantArg(input.expiresAt) ?? null,
+				rate_limit: input.rateLimit ?? null,
+				prefix
+			}, (value) => ({
+				key: apiKeyOf(value),
+				token
+			}));
+		}),
+		list: (organizationId) => call("list_api_keys", { tenant: organizationId ?? null }, (value) => recordsOf(value, "list_api_keys").map(apiKeyOf)),
+		revoke: (id) => call("revoke_api_key", { key: id }, (value) => value === true),
+		rotate: (id, rotateOptions = {}) => AsyncResult.from(async () => {
+			const { id: next, token, hash } = await fresh();
+			return call("rotate_api_key", {
+				key: id,
+				public_id: next,
+				secret_hash: hash,
+				grace: (rotateOptions.grace ?? temporal().Duration.from({ days: 1 })).toString()
+			}, (value) => ({
+				key: apiKeyOf(value),
+				token
+			}));
+		}),
+		verify: (token) => AsyncResult.from(async () => {
+			const parsed = parseApiKey(token);
+			if (!parsed || parsed.prefix !== prefix) return ok({ status: "invalid" });
+			return call("verify_api_key", {
+				public_id: parsed.publicId,
+				secret_hash: await sha256Hex(parsed.secret)
+			}, checkOf);
+		})
+	};
+}
+/**
+* The claims queries run with for a key: `api_key` with `id`, `name`,
+* `scopes` and `organization_id` for the module's `has_scope()` and
+* `api_key_tenant()`, plus `options.claim`.
+*/
+function apiKeyClaims(key, options = {}) {
+	const scopes = key.scopes.includes("*") && options.allPermissions ? [.../* @__PURE__ */ new Set([...key.scopes.filter((scope) => scope !== "*"), ...options.allPermissions])] : key.scopes;
+	const base = {
+		id: key.id,
+		name: key.name,
+		scopes,
+		...key.organizationId ? { organization_id: key.organizationId } : {}
+	};
+	const claims = {
+		sub: key.userId ?? "",
+		role: "authenticated",
+		aud: "authenticated",
+		api_key: base
+	};
+	if (options.claim !== void 0) {
+		const names = options.claim;
+		const claim = names.name;
+		const service = key.userId === void 0 && key.organizationId !== void 0;
+		const roles = service ? options.serviceRoles?.(key) ?? names.serviceRoles : void 0;
+		const target = claim === "api_key" ? base : {
+			id: key.id,
+			name: key.name
+		};
+		target[names.scopes ?? "scopes"] = scopes.filter((scope) => scope !== "*");
+		if (service) target[names.tenant ?? "tenant"] = key.organizationId;
+		if (roles && roles.length > 0) target[names.roles ?? "roles"] = [...roles];
+		claims[claim] = target;
+	}
+	if (options.tenantClaim !== void 0 && key.userId !== void 0 && key.organizationId !== void 0) claims[options.tenantClaim] = key.organizationId;
+	return claims;
+}
+function presented(request, header) {
+	const direct = request.headers.get(header)?.trim();
+	if (direct) return direct;
+	const bearer = request.headers.get("authorization")?.match(/^Bearer\s+(.+)$/i)?.[1]?.trim();
+	return bearer && parseApiKey(bearer) ? bearer : void 0;
+}
+/**
+* Resolves `x-api-key` (or a Bearer token shaped like a key) to an `apiKey`
+* auth state. Requests without one fall through to the JWT and cookie
+* resolution. Pass it to `createServer({ auth: { resolvers: [...] } })`.
+*/
+function apiKeyResolver(options) {
+	const header = options.header ?? "x-api-key";
+	return {
+		name: "api-keys",
+		async resolve(request) {
+			const token = presented(request, header);
+			if (token === void 0) return void 0;
+			const checked = await options.keys.verify(token);
+			if (!checked.ok) return {
+				kind: "invalid",
+				error: checked.error
+			};
+			const check = checked.data;
+			switch (check.status) {
+				case "ok": {
+					const { key } = check;
+					return {
+						kind: "apiKey",
+						keyId: key.id,
+						name: key.name,
+						...key.organizationId ? { organizationId: key.organizationId } : {},
+						...key.userId ? { userId: key.userId } : {},
+						scopes: key.scopes,
+						createdAt: key.createdAt,
+						...key.createdBy ? { createdBy: key.createdBy } : {},
+						claims: apiKeyClaims(key, options)
+					};
+				}
+				case "rate_limited": return {
+					kind: "invalid",
+					error: dbError("rate_limited", "API key rate limit exceeded", {
+						code: "API_KEY_RATE_LIMITED",
+						retryAfter: check.retryAfter
+					})
+				};
+				case "invalid": return {
+					kind: "invalid",
+					error: dbError("unauthorized", "Invalid API key", { code: "INVALID_API_KEY" })
+				};
+				default: return check;
+			}
+		}
+	};
+}
+//#endregion
+//#region src/blocks/api-keys/pipeline.ts
+function withApiKeyAuth(options) {
+	const resolver = apiKeyResolver(options);
+	return defineMiddleware({
+		key: "auth",
+		run: () => async (request) => {
+			const instance = new URL(request.url).pathname;
+			const state = await resolver.resolve(request);
+			if (state?.kind === "apiKey") return { auth: state };
+			return problemResponse(state?.kind === "invalid" ? state.error : dbError("unauthorized", "An API key is required", { code: "API_KEY_REQUIRED" }), {
+				instance,
+				format: options.problem,
+				headers: { "www-authenticate": "Bearer realm=\"api\"" }
+			});
+		}
+	})();
+}
+/**
+* A `@supabase/server` pipeline entry for routes that take API keys
+* (`x-api-key`, or `Authorization: Bearer` with a key): it verifies the key
+* with `keys.verify`, answers a missing, invalid or rate-limited key with
+* Problem Details, and contributes `ctx.auth` and the `withSupabase` keys
+* (`jwtClaims`, `userClaims`, `authMode`) from the key's claims, so
+* `withPostgresClient` and `withBetterPostgres` run queries as the key.
+*
+* ```ts
+* pipeline([withApiKey({ keys }), withPostgresClient(), withBetterPostgres(betterSupabase)()], (req, ctx) => ...)
+* ```
+*/
+function withApiKey(options) {
+	return defineComposite({ build: () => [
+		withApiKeyAuth(options),
+		withJwtClaims(),
+		withUserClaims(),
+		withAuthMode()
+	] })();
+}
+//#endregion
+export { apiKeyChecksum, apiKeyClaims, apiKeyResolver, createApiKeys, parseApiKey, rpcTransport, sqlTransport, withApiKey };

package/dist/blocks/attachments/index.d.ts

@@ -0,0 +1,210 @@
+/// <reference lib="esnext.temporal" />
+import { t as AsyncResult, w as ErrorMapper } from "../../result-D7y2fT87.js";
+import { i as sqlTransport, r as rpcTransport, t as BlockTransport } from "../../block-transport-DvaoPuZ9.js";
+import { r as BlockTemporalOptions } from "../../block-helpers-CKtbFcRv.js";
+import { m as JobHandler } from "../../queue-CLJurhdy.js";
+import { r as EventSink } from "../../cloud-event-C1JCc1bH.js";
+//#region src/blocks/attachments/attachments.d.ts
+interface StorageReply<T> {
+  readonly data: T | null;
+  readonly error: unknown;
+}
+/** The `supabase.storage.from(bucket)` methods attachments use. */
+interface AttachmentBucket {
+  createSignedUploadUrl(path: string): PromiseLike<StorageReply<{
+    readonly signedUrl: string;
+    readonly token: string;
+  }>>;
+  createSignedUrl(path: string, expiresIn: number, options?: {
+    download?: string | boolean;
+  }): PromiseLike<StorageReply<{
+    readonly signedUrl: string;
+  }>>;
+  download(path: string): PromiseLike<StorageReply<Blob>>;
+  remove(paths: string[]): PromiseLike<StorageReply<unknown>>;
+  /** Used by `put`, which uploads from the server. */
+  upload?(path: string, body: Blob | ArrayBuffer | Uint8Array, options?: {
+    readonly contentType?: string;
+    readonly upsert?: boolean;
+  }): PromiseLike<StorageReply<unknown>>;
+}
+/** `supabase.storage`, typed structurally. */
+interface AttachmentStorage {
+  from(bucket: string): AttachmentBucket;
+}
+interface AttachmentsOptions extends BlockTemporalOptions {
+  /** The caller's transport (`rpcTransport(supabase)`). */
+  readonly transport: BlockTransport;
+  /** The caller's `supabase.storage`, so the bucket policies apply. */
+  readonly storage: AttachmentStorage;
+  /** The module schema (`sql.modules.attachments.schema`), default `better_supabase`. */
+  readonly schema?: string;
+  readonly mappers?: readonly ErrorMapper[];
+  /** Must match `sql.modules.attachments.options.requireScan`. Default `true`. */
+  readonly requireScan?: boolean;
+  /** Lifetime of a signed download URL in seconds. Default 300. */
+  readonly downloadTtl?: number;
+}
+type AttachmentStatus = "pending" | "clean" | "infected" | "failed";
+interface Attachment {
+  readonly id: string;
+  /** `undefined` for a file of a subject without a tenant (`tenant: false`). */
+  readonly organizationId: string | undefined;
+  readonly subjectType: string | undefined;
+  readonly subjectId: string | undefined;
+  readonly bucket: string;
+  /** The object path in the bucket, `{organizationId}/attachments/{id}` unless `options.path` says otherwise. */
+  readonly path: string;
+  readonly name: string;
+  readonly mimeType: string;
+  readonly size: number;
+  readonly status: AttachmentStatus;
+  /** What the scanner reported, such as the signature it matched. */
+  readonly scanDetail: string | undefined;
+  /** What `upload` stored with the file; `{}` without any. */
+  readonly metadata: Readonly<Record<string, unknown>>;
+  readonly uploadedBy: string | undefined;
+  readonly createdAt: Temporal.Instant;
+  /** Set by `confirm()` once the object exists. */
+  readonly uploadedAt: Temporal.Instant | undefined;
+  readonly scannedAt: Temporal.Instant | undefined;
+}
+interface NewAttachment {
+  /** `null` for a subject type configured with `tenant: false`. */
+  readonly organizationId: string | null;
+  readonly name: string;
+  readonly mimeType: string;
+  /** Bytes; `confirm()` replaces it with the stored size. */
+  readonly size: number;
+  readonly subjectType?: string;
+  readonly subjectId?: string;
+  /** App data about the file, such as a caption or its source, kept with the record. */
+  readonly metadata?: Readonly<Record<string, unknown>>;
+}
+interface AttachmentUpload {
+  readonly attachment: Attachment;
+  /** PUT the file here, or pass `token` to `uploadToSignedUrl(path, token, file)`. */
+  readonly signedUrl: string;
+  readonly token: string;
+}
+interface AttachmentDownload {
+  readonly attachment: Attachment;
+  readonly signedUrl: string;
+}
+interface Attachments {
+  /** Creates the pending record and a signed upload URL for its path. */
+  upload(attachment: NewAttachment): AsyncResult<AttachmentUpload>;
+  /** Marks the upload done after the file is stored; emits `attachment.uploaded`. */
+  confirm(id: string): AsyncResult<Attachment>;
+  get(id: string): AsyncResult<Attachment>;
+  list(organizationId: string | null, subject?: {
+    readonly type: string;
+    readonly id: string;
+  }): AsyncResult<readonly Attachment[]>;
+  /**
+   * A signed URL for a file the scanner passed. `invalid_request` with hint
+   * `ATTACHMENT_NOT_SCANNED` until then, and for an infected file.
+   */
+  download(id: string, options?: {
+    readonly as?: string | boolean;
+  }): AsyncResult<AttachmentDownload>;
+  /** Deletes the file, then the record (the uploader, or `attachments.manage`). */
+  remove(id: string): AsyncResult<boolean>;
+  /**
+   * Creates the record, uploads `file` from the server and confirms it, for
+   * files the server makes or fetches (an export, a generated PDF, an
+   * import). Returns the confirmed attachment, which still waits for the
+   * scan when the module requires one.
+   */
+  put(attachment: NewAttachment, file: Blob | ArrayBuffer | Uint8Array): AsyncResult<Attachment>;
+  /**
+   * The file's bytes, for server-side processing, behind the same scan gate
+   * as `download`: `ATTACHMENT_NOT_SCANNED` until the scan passes.
+   */
+  read(id: string): AsyncResult<{
+    readonly attachment: Attachment;
+    readonly file: Blob;
+  }>;
+}
+/** Attachments as the caller: the table's and the bucket's policies apply. */
+export declare function createAttachments(options: AttachmentsOptions): Attachments;
+/** A scanner's verdict on one file. */
+interface ScanVerdict {
+  readonly status: "clean" | "infected";
+  /** Stored as `scan_detail`, such as the matched signature. */
+  readonly detail?: string;
+}
+interface AttachmentScannerOptions extends BlockTemporalOptions {
+  /** A service-role transport: `set_attachment_status()` is granted to `service_role` only. */
+  readonly transport: BlockTransport;
+  /** A service-role `supabase.storage`, to read pending files. */
+  readonly storage: AttachmentStorage;
+  readonly schema?: string;
+  /** Scans the file (ClamAV, a scanning API). A throw records `failed` and rethrows. */
+  readonly scan: (file: Blob, attachment: Attachment, signal?: AbortSignal) => ScanVerdict | Promise<ScanVerdict>;
+  /** The outbox `typePrefix`. Default `dev.better-supabase`. */
+  readonly typePrefix?: string;
+}
+/** The payload `job` expects. */
+interface AttachmentScanJob {
+  readonly attachmentId: string;
+}
+interface AttachmentScanner {
+  /** Scans one uploaded file and records the verdict. */
+  scan(id: string, signal?: AbortSignal): AsyncResult<Attachment>;
+  /** A jobs handler: `queue.work('attachment-scans', scanner.job)`. */
+  readonly job: JobHandler<AttachmentScanJob>;
+  /** An outbox sink that scans each `attachment.uploaded` event's file. */
+  sink(): EventSink;
+}
+/**
+ * Scans uploaded files with the app's `scan` function and records `clean`,
+ * `infected` or `failed`. A file already clean or infected is not scanned
+ * again, so replayed events and retried jobs are safe.
+ */
+export declare function createAttachmentScanner(options: AttachmentScannerOptions): AttachmentScanner;
+/** A scanned object in any bucket (`scanned_objects`). */
+interface ScannedObject {
+  readonly bucket: string;
+  readonly path: string;
+  readonly status: AttachmentStatus;
+  readonly detail: string | undefined;
+  readonly scannedAt: Temporal.Instant | undefined;
+}
+interface ObjectScannerOptions extends BlockTemporalOptions {
+  /** A service-role transport: `set_object_scan()` is granted to `service_role` only. */
+  readonly transport: BlockTransport;
+  /** A service-role `supabase.storage`, to read the objects. */
+  readonly storage: AttachmentStorage;
+  readonly schema?: string;
+  /** Scans the file. A throw records `failed` and rethrows. */
+  readonly scan: (file: Blob, object: {
+    readonly bucket: string;
+    readonly path: string;
+  }, signal?: AbortSignal) => ScanVerdict | Promise<ScanVerdict>;
+  /** The outbox `typePrefix`. Default `dev.better-supabase`. */
+  readonly typePrefix?: string;
+}
+/** The payload `ObjectScanner.job` expects. */
+interface ObjectScanJob {
+  readonly bucket: string;
+  readonly path: string;
+}
+interface ObjectScanner {
+  /** Scans one object and records the verdict; a clean or infected object is not scanned again. */
+  scan(bucket: string, path: string, signal?: AbortSignal): AsyncResult<ScannedObject>;
+  /** A jobs handler: `queue.work('object-scans', scanner.job)`. */
+  readonly job: JobHandler<ObjectScanJob>;
+  /** An outbox sink that scans each `object.uploaded` event's object. */
+  sink(): EventSink;
+}
+/**
+ * The scan gate for objects outside the attachments table, such as a file
+ * drive or avatars: scans an object with the app's `scan` function and
+ * records the verdict in `scanned_objects`, which storage policies read with
+ * `object_clean(bucket_id, name)`. With `options.scanBuckets`, new objects in
+ * those buckets get a pending row and an `object.uploaded` event.
+ */
+export declare function createObjectScanner(options: ObjectScannerOptions): ObjectScanner;
+//#endregion
+export { type Attachment, type AttachmentBucket, type AttachmentDownload, type AttachmentScanJob, type AttachmentScanner, type AttachmentScannerOptions, type AttachmentStatus, type AttachmentStorage, type AttachmentUpload, type Attachments, type AttachmentsOptions, type BlockTransport, type NewAttachment, type ObjectScanJob, type ObjectScanner, type ObjectScannerOptions, type ScanVerdict, type ScannedObject, rpcTransport, sqlTransport };