better-supabase 0.7.1 → 0.9.0

package/dist/api-keys-BEQatEUW.js

@@ -0,0 +1,318 @@
+import { n as dbError } from "./errors-8i6tSICm.js";
+import { t as temporal } from "./temporal-required-DqRzr7i0.js";
+import { a as ok, t as AsyncResult } from "./result-BlgnMB0H.js";
+import { C as optionalText, D as recordOf, F as stringsOf, I as textOf, N as sha256Hex, S as optionalInstant, k as recordsOf, m as instantArg, n as applyTemporal, o as blockCall } from "./block-helpers-CfG_MvDR.js";
+import { r as withBlockHooks } from "./block-hooks-BsXncUlZ.js";
+import { c as withFields, n as blockFields, r as extraFieldsArg, t as allWithFields } from "./block-fields-ffD6Gxe4.js";
+//#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;
+	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 kind = optionalText(row["kind"]);
+	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"]),
+		...kind ? { kind } : {},
+		...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 fields = blockFields(options.fields, "API key fields");
+	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 created = (fn, args, token) => call(fn, args, (value) => value).andThen((value) => withFields(fields, value, apiKeyOf(value))).map((key) => ({
+		key,
+		token
+	}));
+	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 withBlockHooks({
+		create: ({ name, organizationId, personal, scopes, kind, expiresAt, rateLimit, ...extra }) => AsyncResult.from(() => extraFieldsArg(fields, extra)).andThen(async (more) => {
+			const { id, token, hash } = await fresh();
+			return created("create_api_key", {
+				name,
+				public_id: id,
+				secret_hash: hash,
+				tenant: organizationId ?? null,
+				personal: personal ?? false,
+				scopes: scopes ?? [],
+				expires_at: instantArg(expiresAt) ?? null,
+				rate_limit: rateLimit ?? null,
+				prefix,
+				kind: kind ?? null,
+				...more
+			}, token);
+		}),
+		list: (organizationId) => call("list_api_keys", { tenant: organizationId ?? null }, (value) => recordsOf(value, "list_api_keys").map((raw) => [raw, apiKeyOf(raw)])).andThen((rows) => allWithFields(fields, rows)),
+		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 created("rotate_api_key", {
+				key: id,
+				public_id: next,
+				secret_hash: hash,
+				grace: (rotateOptions.grace ?? temporal().Duration.from({ days: 1 })).toString()
+			}, 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)
+			}, (value) => value).andThen(async (value) => {
+				const check = checkOf(value);
+				if (check.status !== "ok") return ok(check);
+				const raw = recordOf(value, "verify_api_key")["key"];
+				const key = await withFields(fields, raw, check.key);
+				return key.ok ? ok({
+					status: "ok",
+					key: key.data
+				}) : key;
+			});
+		}),
+		isApiKey: (token) => token.trim().startsWith(`${prefix}_`)
+	}, options.hooks, {
+		block: "api-keys",
+		...options.logger ? { logger: options.logger } : {}
+	});
+}
+const RESERVED_CLAIMS = /* @__PURE__ */ new Set([
+	"sub",
+	"role",
+	"aud",
+	"api_key"
+]);
+/**
+* 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` and `options.claims`.
+*/
+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 extra = Object.entries(options.claims?.(key) ?? {}).filter(([name]) => !RESERVED_CLAIMS.has(name));
+	const claims = {
+		...Object.fromEntries(extra),
+		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, keys) {
+	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) || keys.isApiKey?.(bearer) === true) ? bearer : void 0;
+}
+/**
+* Resolves `x-api-key` (or a Bearer token shaped like a key, or one with the
+* key prefix) 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, options.keys);
+			if (token === void 0) return;
+			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
+export { parseApiKey as a, createApiKeys as i, apiKeyClaims as n, apiKeyResolver as r, apiKeyChecksum as t };

package/dist/api-keys-BYoGCM9p.d.ts

@@ -0,0 +1,205 @@
+/// <reference lib="esnext.temporal" />
+import { t as AsyncResult } from "./result-Cj3yWhjH.js";
+import { n as Logger } from "./logger-DWVYUmwi.js";
+import { t as StandardSchemaV1 } from "./standard-C3_AAF3g.js";
+import { n as AuthResolver } from "./resolve-w9EpHzuM.js";
+import { t as BlockTransport } from "./block-transport-DaGGXjIw.js";
+import { r as BlockTemporalOptions } from "./block-helpers-C86hPEjI.js";
+import { n as BlockHooks } from "./block-hooks-BLPWD3Jt.js";
+import { r as FieldsOf } from "./block-fields-5UA84ZUg.js";
+import { JWTClaims } from "@supabase/server";
+//#region src/blocks/api-keys/api-keys.d.ts
+type ApiKeyState = "active" | "grace" | "revoked" | "expired";
+interface ApiKey {
+  readonly id: string;
+  /** Set for a tenant key, and for a personal key limited to one tenant. */
+  readonly organizationId?: string;
+  /** Set for a personal key: it acts as this user. */
+  readonly userId?: string;
+  readonly name: string;
+  readonly prefix: string;
+  readonly publicId: string;
+  readonly scopes: readonly string[];
+  /** What the key is for, one of `blocks.api-keys.options.kinds`. */
+  readonly kind?: string;
+  /** Requests per minute, when the key has a limit. */
+  readonly rateLimit?: number;
+  readonly expiresAt?: Temporal.Instant;
+  readonly lastUsedAt?: Temporal.Instant;
+  /** In the future while a rotated key's grace period runs. */
+  readonly revokedAt?: Temporal.Instant;
+  readonly rotatedFrom?: string;
+  readonly createdBy?: string;
+  readonly createdAt: Temporal.Instant;
+  readonly state: ApiKeyState;
+  readonly successorId?: string;
+}
+/** A new key. `token` is shown once: only its hash is stored. */
+interface CreatedApiKey<F extends object = Record<never, never>> {
+  readonly key: ApiKey & F;
+  readonly token: string;
+}
+interface CreateApiKeyInput {
+  readonly name: string;
+  /** The tenant the key acts in. Required unless `personal`. */
+  readonly organizationId?: string;
+  /** Acts as the signed-in user (in `organizationId` only, when set). */
+  readonly personal?: boolean;
+  /** `*` grants every scope. */
+  readonly scopes?: readonly string[];
+  /** What the key is for, one of `blocks.api-keys.options.kinds`. */
+  readonly kind?: string;
+  readonly expiresAt?: Temporal.Instant;
+  /** Requests per minute. */
+  readonly rateLimit?: number;
+}
+type ApiKeyCheck<F extends object = Record<never, never>> = {
+  readonly status: "ok";
+  readonly key: ApiKey & F;
+} | {
+  readonly status: "invalid";
+} | {
+  readonly status: "rate_limited";
+  readonly retryAfter: number;
+};
+/** `F` is the extra key fields `options.fields` describes. */
+interface ApiKeys<F extends object = Record<never, never>> {
+  /** Keys besides the input's own are the key's extra columns. */
+  create(input: CreateApiKeyInput & Partial<F>): AsyncResult<CreatedApiKey<F>>;
+  /** A tenant's keys for its managers (the caller's own otherwise), or the caller's personal keys. */
+  list(organizationId?: string): AsyncResult<readonly (ApiKey & F)[]>;
+  revoke(id: string): AsyncResult<boolean>;
+  /**
+   * A new token for the key, with its extra columns; the old one keeps
+   * working for `grace` (one day by default).
+   */
+  rotate(id: string, options?: {
+    readonly grace?: Temporal.Duration;
+  }): AsyncResult<CreatedApiKey<F>>;
+  /**
+   * Checks a presented token and counts the request. Needs a service
+   * transport. A token that doesn't parse, such as `<prefix>_bad`, is
+   * `invalid`.
+   */
+  verify(token: string): AsyncResult<ApiKeyCheck<F>>;
+  /**
+   * Whether a token claims to be one of these keys: it starts with the
+   * prefix and `_`, well formed or not. Use it to send a Bearer token to
+   * `verify` instead of JWT verification.
+   */
+  isApiKey(token: string): boolean;
+}
+interface ApiKeysOptions<S extends StandardSchemaV1 | undefined = undefined> extends BlockTemporalOptions {
+  /**
+   * A Standard Schema for the key columns the app adds
+   * (`blocks.api-keys.options.extraColumns`), keyed by column name. It
+   * types and parses them on every read, and validates them on `create`,
+   * which returns a `validation` error for a bad value.
+   */
+  readonly fields?: S;
+  /** `withBlockHooks` hooks around the client's methods. */
+  readonly hooks?: NoInfer<BlockHooks<ApiKeys<FieldsOf<S>>>>;
+  /** Receives the errors `after` hooks throw. Default: `console`. */
+  readonly logger?: Logger;
+  readonly transport: BlockTransport;
+  readonly schema?: string;
+  /** The token's first segment, lowercase letters and digits. Defaults to `bs`. */
+  readonly prefix?: string;
+}
+interface ParsedApiKey {
+  readonly prefix: string;
+  readonly publicId: string;
+  readonly secret: string;
+  /** Whether the token ends in a checksum; keys created before it have none. */
+  readonly checksum: boolean;
+}
+/**
+ * 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.
+ */
+declare function apiKeyChecksum(text: string): string;
+/**
+ * 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`.
+ */
+declare function parseApiKey(token: string): ParsedApiKey | undefined;
+/**
+ * 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.
+ */
+declare function createApiKeys<S extends StandardSchemaV1 | undefined = undefined>(options: ApiKeysOptions<S>): ApiKeys<FieldsOf<S>>;
+/**
+ * A second claim for an authorization provider's SQL functions, with the
+ * field names they read. Every field but `name` is optional.
+ */
+interface ApiKeyExtraClaim {
+  /** The claim. `api_key` adds the fields to the module's own claim. */
+  readonly name: string;
+  /** The field with the permission keys, default `scopes`. */
+  readonly scopes?: string;
+  /** The field with a tenant key's tenant, default `tenant`. */
+  readonly tenant?: string;
+  /** The field with a tenant key's roles, default `roles`. */
+  readonly roles?: string;
+  /** The roles a tenant key holds in its tenant, unless `serviceRoles` in the options answers. */
+  readonly serviceRoles?: readonly string[];
+}
+/** The claims a key's JWT always carries, which `claims` cannot set. */
+type ApiKeyReservedClaim = "sub" | "role" | "aud" | "api_key";
+/** Extra claims from the `claims` hook: any key but the reserved ones. */
+type ApiKeyExtraClaims = Readonly<Record<string, unknown>> & { readonly [K in ApiKeyReservedClaim]?: never; };
+/** `F` is the extra key fields of `createApiKeys({ fields })`. */
+interface ApiKeyClaimsOptions<F extends object = Record<never, never>> {
+  /**
+   * Also write the claim an authorization provider's SQL functions read:
+   * the scopes as a ceiling, and a tenant key's tenant and roles.
+   */
+  readonly claim?: ApiKeyExtraClaim;
+  /** The roles a tenant key holds in its tenant; default `claim.serviceRoles`. */
+  readonly serviceRoles?: (key: ApiKey & F) => readonly string[];
+  /**
+   * Claims to add for a key, such as one read from its `kind` or an extra
+   * column. `sub`, `role`, `aud`, `api_key` and the claims the other options
+   * write keep their values.
+   */
+  readonly claims?: (key: ApiKey & F) => ApiKeyExtraClaims;
+  /**
+   * The permission keys `*` stands for in `claim`, which has no wildcard,
+   * so without this a key with `*` allows nothing there.
+   */
+  readonly allPermissions?: readonly string[];
+  /**
+   * The claim that narrows a provider's functions to one tenant (such as
+   * `tenant_id`), set for a personal key limited to a tenant.
+   */
+  readonly tenantClaim?: string;
+}
+interface ApiKeyResolverOptions<F extends object = Record<never, never>> extends ApiKeyClaimsOptions<F> {
+  /**
+   * `createApiKeys` over a service transport. With `isApiKey`, a Bearer
+   * token with the key prefix is checked as a key even when it is
+   * malformed, so it gets `INVALID_API_KEY`.
+   */
+  readonly keys: Pick<ApiKeys<F>, "verify"> & Partial<Pick<ApiKeys<F>, "isApiKey">>;
+  /** The header that carries the key besides `Authorization: Bearer`. Defaults to `x-api-key`. */
+  readonly header?: string;
+}
+/**
+ * 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` and `options.claims`.
+ */
+declare function apiKeyClaims<F extends object = Record<never, never>>(key: ApiKey & F, options?: ApiKeyClaimsOptions<F>): JWTClaims;
+/**
+ * Resolves `x-api-key` (or a Bearer token shaped like a key, or one with the
+ * key prefix) to an `apiKey` auth state. Requests without one fall through
+ * to the JWT and cookie resolution. Pass it to `createServer({ auth: { resolvers: [...] } })`.
+ */
+declare function apiKeyResolver<F extends object = Record<never, never>>(options: ApiKeyResolverOptions<F>): AuthResolver;
+//#endregion
+export { createApiKeys as _, ApiKeyExtraClaims as a, ApiKeyState as c, CreateApiKeyInput as d, CreatedApiKey as f, apiKeyResolver as g, apiKeyClaims as h, ApiKeyExtraClaim as i, ApiKeys as l, apiKeyChecksum as m, ApiKeyCheck as n, ApiKeyReservedClaim as o, ParsedApiKey as p, ApiKeyClaimsOptions as r, ApiKeyResolverOptions as s, ApiKey as t, ApiKeysOptions as u, parseApiKey as v };