okengine 0.17.2 → 0.18.3

package/src/auth/identity-sql.ts

@@ -0,0 +1,314 @@
+/**
+ * SQL persist / hydrate for {@link UserIdentityRow} + {@link UserAccountRow}.
+ *
+ * Host path: public schema on the app `store.sql()` connection
+ * (`sharedSqlConn` / `DATABASE_URL`), mirroring `api-key-sql.ts`.
+ * The identity store hydrates `oke_identities` / `oke_credentials` at host
+ * boot and write-through-persists every user/account row thereafter.
+ */
+
+import type { SqlConnection } from "../drivers/types.ts";
+import { AUTH_TABLES } from "./tables.ts";
+import type { IdentityStore, UserAccountRow, UserIdentityRow } from "./identity.ts";
+
+/** Minimal SQL executor for the identity tables. */
+export interface IdentitySqlExec {
+  execute(sql: string, params: readonly unknown[]): Promise<void>;
+  all(sql: string): Promise<readonly Record<string, unknown>[]>;
+}
+
+const USER_COLUMNS = "id, email, name, email_verified, status, created_at, updated_at, extra_json";
+const ACCOUNT_COLUMNS =
+  "id, user_id, provider, provider_account_id, password_hash, created_at, updated_at";
+
+/**
+ * Persist one user row to `oke_identities`.
+ *
+ * @param sql - Executor
+ * @param row - User row
+ * @param table - Physical table
+ */
+export async function persistIdentityUserRow(
+  sql: IdentitySqlExec,
+  row: UserIdentityRow,
+  table: string = AUTH_TABLES.identities,
+): Promise<void> {
+  await sql.execute(
+    `INSERT INTO ${table} (${USER_COLUMNS})
+     VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+     ON CONFLICT(id) DO UPDATE SET
+       email = excluded.email,
+       name = excluded.name,
+       email_verified = excluded.email_verified,
+       status = excluded.status,
+       created_at = excluded.created_at,
+       updated_at = excluded.updated_at,
+       extra_json = excluded.extra_json`,
+    [
+      row.id,
+      row.email,
+      row.name,
+      row.emailVerified ? 1 : 0,
+      row.status,
+      row.createdAt,
+      row.updatedAt,
+      JSON.stringify(row.extra),
+    ],
+  );
+}
+
+/**
+ * Persist one account row to `oke_credentials`.
+ *
+ * @param sql - Executor
+ * @param row - Account row
+ * @param table - Physical table
+ */
+export async function persistIdentityAccountRow(
+  sql: IdentitySqlExec,
+  row: UserAccountRow,
+  table: string = AUTH_TABLES.credentials,
+): Promise<void> {
+  await sql.execute(
+    `INSERT INTO ${table} (${ACCOUNT_COLUMNS})
+     VALUES (?, ?, ?, ?, ?, ?, ?)
+     ON CONFLICT(id) DO UPDATE SET
+       user_id = excluded.user_id,
+       provider = excluded.provider,
+       provider_account_id = excluded.provider_account_id,
+       password_hash = excluded.password_hash,
+       created_at = excluded.created_at,
+       updated_at = excluded.updated_at`,
+    [
+      row.id,
+      row.userId,
+      row.provider,
+      row.providerAccountId,
+      row.passwordHash,
+      row.createdAt,
+      row.updatedAt,
+    ],
+  );
+}
+
+/**
+ * Bind write-through persist hooks on a store.
+ *
+ * @param store - Identity store
+ * @param sql - Executor
+ * @param userTable - Physical `oke_identities`
+ * @param accountTable - Physical `oke_credentials`
+ */
+export function bindIdentitySqlPersist(
+  store: IdentityStore,
+  sql: IdentitySqlExec,
+  userTable: string = AUTH_TABLES.identities,
+  accountTable: string = AUTH_TABLES.credentials,
+): void {
+  store.persistUser = (row) => persistIdentityUserRow(sql, row, userTable);
+  store.persistAccount = (row) => persistIdentityAccountRow(sql, row, accountTable);
+}
+
+/**
+ * Load every identity + credential row into a store, rebuilding derived maps.
+ *
+ * @param sql - Executor
+ * @param store - Destination store
+ * @param userTable - Physical `oke_identities`
+ * @param accountTable - Physical `oke_credentials`
+ */
+export async function hydrateIdentityStore(
+  sql: IdentitySqlExec,
+  store: IdentityStore,
+  userTable: string = AUTH_TABLES.identities,
+  accountTable: string = AUTH_TABLES.credentials,
+): Promise<void> {
+  const users = await sql.all(`SELECT * FROM ${userTable}`);
+  for (const raw of users) {
+    const row = userFromSql(raw);
+    if (!row) continue;
+    store.users.set(row.id, row);
+    if (row.email) store.byEmail.set(normalizeKey(row.email), row.id);
+  }
+  const accounts = await sql.all(`SELECT * FROM ${accountTable}`);
+  for (const raw of accounts) {
+    const row = accountFromSql(raw);
+    if (!row) continue;
+    store.accounts.set(row.id, row);
+    store.byProvider.set(`${row.provider}:${row.providerAccountId}`, row.id);
+  }
+}
+
+/**
+ * Create public `oke_identities` / `oke_credentials` when missing.
+ *
+ * @param conn - Shared SQL connection
+ * @param userTable - Physical table
+ * @param accountTable - Physical table
+ */
+export async function ensureIdentityTables(
+  conn: SqlConnection,
+  userTable: string = AUTH_TABLES.identities,
+  accountTable: string = AUTH_TABLES.credentials,
+): Promise<void> {
+  await conn.exec(
+    `CREATE TABLE IF NOT EXISTS ${userTable} (
+      id TEXT PRIMARY KEY NOT NULL,
+      email TEXT NOT NULL,
+      name TEXT NOT NULL,
+      email_verified INTEGER NOT NULL DEFAULT 0,
+      status TEXT NOT NULL DEFAULT 'active',
+      created_at BIGINT NOT NULL,
+      updated_at BIGINT NOT NULL,
+      extra_json TEXT NOT NULL DEFAULT '{}'
+    )`,
+  );
+  await conn.exec(
+    `CREATE TABLE IF NOT EXISTS ${accountTable} (
+      id TEXT PRIMARY KEY NOT NULL,
+      user_id TEXT NOT NULL,
+      provider TEXT NOT NULL,
+      provider_account_id TEXT NOT NULL,
+      password_hash TEXT,
+      created_at BIGINT NOT NULL,
+      updated_at BIGINT NOT NULL
+    )`,
+  );
+  await conn.exec(
+    `CREATE INDEX IF NOT EXISTS ${accountTable}_provider_idx ON ${accountTable} (provider, provider_account_id)`,
+  );
+  await conn.exec(
+    `CREATE INDEX IF NOT EXISTS ${accountTable}_user_idx ON ${accountTable} (user_id)`,
+  );
+}
+
+/** Runtime that can open the app's shared primary SQL connection. */
+export interface HostIdentitySqlRuntime {
+  primarySql(): Promise<SqlConnection | undefined>;
+}
+
+/**
+ * Adapt a driver connection to {@link IdentitySqlExec}.
+ *
+ * @param conn - Shared `store.sql()` connection
+ */
+export function identitySqlExec(conn: SqlConnection): IdentitySqlExec {
+  return {
+    execute: async (sql, params) => {
+      await conn.exec(sql, params);
+    },
+    all: async (sql) => conn.query(sql),
+  };
+}
+
+/**
+ * Hydrate and write-through-persist a host {@link IdentityStore} on `conn`.
+ *
+ * Leaves already-bound `persist` hooks in place (injected test stores).
+ *
+ * @param conn - App SQL connection (`sharedSqlConn`)
+ * @param store - `gate.auth.identities`
+ */
+export async function bindHostIdentitySql(
+  conn: SqlConnection,
+  store: IdentityStore,
+): Promise<void> {
+  await ensureIdentityTables(conn);
+  const exec = identitySqlExec(conn);
+  await hydrateIdentityStore(exec, store);
+  if (!store.persistUser || !store.persistAccount) {
+    bindIdentitySqlPersist(store, exec);
+  }
+}
+
+/**
+ * Bind host identity persist through {@link HostIdentitySqlRuntime.primarySql}.
+ *
+ * No-ops when the store runtime has no SQL driver (in-memory-only apps).
+ *
+ * @param runtime - Booted `store` element
+ * @param store - `gate.auth.identities`
+ */
+export async function bindHostIdentitySqlFromStore(
+  runtime: HostIdentitySqlRuntime,
+  store: IdentityStore,
+): Promise<void> {
+  const conn = await runtime.primarySql();
+  if (!conn) return;
+  await bindHostIdentitySql(conn, store);
+}
+
+function userFromSql(raw: Record<string, unknown>): UserIdentityRow | null {
+  const id = asString(raw.id ?? raw.ID);
+  const email = asString(raw.email);
+  if (!id || !email) return null;
+  return {
+    id,
+    email,
+    name: asString(raw.name) ?? "",
+    emailVerified: asBool(raw.email_verified ?? raw.emailVerified),
+    status: raw.status === "suspended" ? "suspended" : "active",
+    createdAt: asNumber(raw.created_at ?? raw.createdAt),
+    updatedAt: asNumber(raw.updated_at ?? raw.updatedAt),
+    extra: asExtra(raw.extra_json ?? raw.extra),
+  };
+}
+
+function accountFromSql(raw: Record<string, unknown>): UserAccountRow | null {
+  const id = asString(raw.id ?? raw.ID);
+  const userId = asString(raw.user_id ?? raw.userId);
+  const provider = asString(raw.provider);
+  const providerAccountId = asString(raw.provider_account_id ?? raw.providerAccountId);
+  if (!id || !userId || !provider || !providerAccountId) return null;
+  return {
+    id,
+    userId,
+    provider,
+    providerAccountId,
+    passwordHash: asNullableString(raw.password_hash ?? raw.passwordHash),
+    createdAt: asNumber(raw.created_at ?? raw.createdAt),
+    updatedAt: asNumber(raw.updated_at ?? raw.updatedAt),
+  };
+}
+
+function normalizeKey(email: string): string {
+  return email.trim().toLowerCase();
+}
+
+function asString(value: unknown): string | null {
+  return typeof value === "string" && value.length > 0 ? value : null;
+}
+
+function asNullableString(value: unknown): string | null {
+  return typeof value === "string" ? value : null;
+}
+
+function asNumber(value: unknown): number {
+  if (typeof value === "number" && Number.isFinite(value)) return value;
+  if (typeof value === "string" && value.length > 0) {
+    const n = Number(value);
+    return Number.isFinite(n) ? n : 0;
+  }
+  return 0;
+}
+
+function asBool(value: unknown): boolean {
+  return value === 1 || value === true || value === "1" || value === "true";
+}
+
+function asExtra(value: unknown): Record<string, unknown> {
+  if (value && typeof value === "object" && !Array.isArray(value)) {
+    return value as Record<string, unknown>;
+  }
+  if (typeof value === "string" && value.length > 0) {
+    try {
+      const parsed: unknown = JSON.parse(value);
+      if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+        return parsed as Record<string, unknown>;
+      }
+    } catch {
+      return {};
+    }
+  }
+  return {};
+}

package/src/auth/identity.ts

@@ -39,6 +39,10 @@ export interface IdentityStore {
   accounts: Map<string, UserAccountRow>;
   /** `provider:providerAccountId` → account id. */
   byProvider: Map<string, string>;
+  /** Optional write-through user persist (SQL). Bound at host boot. */
+  persistUser?: (row: UserIdentityRow) => void | Promise<void>;
+  /** Optional write-through account persist (SQL). Bound at host boot. */
+  persistAccount?: (row: UserAccountRow) => void | Promise<void>;
 }
 
 /**
@@ -84,11 +88,11 @@ export function normalizeEmail(email: string): string {
  * @param email - Normalized email
  * @param now - Clock
  */
-export function ensureUserByEmail(
+export async function ensureUserByEmail(
   store: IdentityStore,
   email: string,
   now: number,
-): UserIdentityRow {
+): Promise<UserIdentityRow> {
   const existingId = store.byEmail.get(email);
   if (existingId) {
     const existing = store.users.get(existingId);
@@ -107,6 +111,7 @@ export function ensureUserByEmail(
   };
   store.users.set(id, user);
   store.byEmail.set(email, id);
+  await store.persistUser?.(user);
   return user;
 }
 
@@ -164,6 +169,7 @@ export async function createUserWithPassword(
   store.byEmail.set(email, id);
   store.accounts.set(accountId, account);
   store.byProvider.set(`credential:${email}`, accountId);
+  await Promise.all([store.persistUser?.(user), store.persistAccount?.(account)]);
   return user;
 }
 
@@ -201,6 +207,138 @@ export function getUserById(store: IdentityStore, id: string): UserIdentityRow |
   return store.users.get(id);
 }
 
+/** Options for {@link linkOrProvision}. */
+export interface LinkOrProvisionOptions {
+  /** Provider name (`magic-link`, `otp`, `passkey`, `username`, `anonymous`). */
+  readonly provider: string;
+  /** Provider-scoped subject (email, phone, username, credential id). */
+  readonly providerAccountId: string;
+  /** Email to attach to a freshly provisioned user (normalized by the store). */
+  readonly email?: string;
+  /** Email-verified claim (only when provisioning). */
+  readonly emailVerified?: boolean;
+  /** Display name when provisioning. */
+  readonly name?: string;
+  /** Optional password hash for the account row. */
+  readonly passwordHash?: string | null;
+  /** Currently authenticated `fx.auth.userId`, when the request is authenticated. */
+  readonly currentUserId?: string;
+  /** Injectable clock. */
+  readonly now?: () => number;
+}
+
+/** Result of {@link linkOrProvision}. */
+export interface LinkedCredential {
+  readonly user: UserIdentityRow;
+  readonly account: UserAccountRow;
+  /** `true` when a new account was written (vs plain sign-in resolution). */
+  readonly created: boolean;
+}
+
+/**
+ * The single shared credential-write path across Gate auth method plugins.
+ *
+ * Enforces the locked account-linking rule centrally:
+ * - An existing `provider:providerAccountId` resolves to its user (sign-in).
+ * - A new credential may attach to an existing user ONLY when the request is
+ *   already authenticated as that user (`currentUserId` matches).
+ * - An unauthenticated new credential whose email is already owned by another
+ *   user is REFUSED (`email_in_use`) — never auto-linked by email match alone.
+ *
+ * @param store - Shared identity store
+ * @param options - Credential + linking context
+ */
+export async function linkOrProvision(
+  store: IdentityStore,
+  options: LinkOrProvisionOptions,
+): Promise<LinkedCredential> {
+  const { provider, providerAccountId } = options;
+  const now = options.now ?? (() => Date.now());
+  const key = `${provider}:${providerAccountId}`;
+
+  // 1. Existing credential → plain sign-in resolution (no linking needed).
+  const existingAccountId = store.byProvider.get(key);
+  if (existingAccountId) {
+    const account = store.accounts.get(existingAccountId);
+    const user = account ? store.users.get(account.userId) : undefined;
+    if (account && user) return { user, account, created: false };
+  }
+
+  const email = options.email ? normalizeEmail(options.email) : undefined;
+  const emailOwnerId = email ? store.byEmail.get(email) : undefined;
+  if (emailOwnerId) {
+    if (options.currentUserId) {
+      if (emailOwnerId !== options.currentUserId) {
+        throw new IdentityError("email_conflict", "email belongs to another user");
+      }
+    } else {
+      throw new IdentityError("email_in_use", "email already registered to another credential");
+    }
+  }
+
+  const t = now();
+  const userId = options.currentUserId ?? crypto.randomUUID();
+  const existingUser = store.users.get(userId);
+  const user: UserIdentityRow = existingUser ?? {
+    id: userId,
+    email: email ?? "",
+    name: options.name?.trim() || (email ? email.split("@")[0] || "user" : "user"),
+    emailVerified: options.emailVerified === true,
+    status: "active",
+    createdAt: t,
+    updatedAt: t,
+    extra: {},
+  };
+  const account: UserAccountRow = {
+    id: crypto.randomUUID(),
+    userId,
+    provider,
+    providerAccountId,
+    passwordHash: options.passwordHash ?? null,
+    createdAt: t,
+    updatedAt: t,
+  };
+
+  const userIsNew = !store.users.has(userId);
+  store.users.set(userId, user);
+  if (email) store.byEmail.set(email, userId);
+  store.accounts.set(account.id, account);
+  store.byProvider.set(key, account.id);
+  if (userIsNew) await store.persistUser?.(user);
+  await store.persistAccount?.(account);
+  return { user, account, created: true };
+}
+
+/**
+ * Ensure a user row exists for `userId` (defensive — two-factor enable on an
+ * established session principal).
+ *
+ * @param store - Shared identity store
+ * @param userId - Existing principal id
+ * @param now - Clock
+ */
+export async function ensureUserExists(
+  store: IdentityStore,
+  userId: string,
+  now: number,
+): Promise<UserIdentityRow> {
+  const existing = store.users.get(userId);
+  if (existing) return existing;
+  const user: UserIdentityRow = {
+    id: userId,
+    email: "",
+    name: "user",
+    emailVerified: false,
+    status: "active",
+    createdAt: now,
+    updatedAt: now,
+    extra: {},
+  };
+  store.users.set(userId, user);
+  await store.persistUser?.(user);
+  return user;
+}
+
 /** Identity-plane error. */
 export class IdentityError extends Error {
   readonly code: string;

package/src/auth/index.ts

@@ -88,11 +88,15 @@ export {
   getUserById,
   normalizeEmail,
   ensureUserByEmail,
+  ensureUserExists,
+  linkOrProvision,
   IdentityError,
   type IdentityStore,
   type UserIdentityRow,
   type UserAccountRow,
   type CreateUserWithPasswordOptions,
+  type LinkOrProvisionOptions,
+  type LinkedCredential,
 } from "./identity.ts";
 
 export {
@@ -196,6 +200,19 @@ export {
   type HostApiKeySqlRuntime,
 } from "./api-key-sql.ts";
 
+export {
+  identitySqlExec,
+  bindIdentitySqlPersist,
+  bindHostIdentitySql,
+  bindHostIdentitySqlFromStore,
+  ensureIdentityTables,
+  hydrateIdentityStore,
+  persistIdentityUserRow,
+  persistIdentityAccountRow,
+  type IdentitySqlExec,
+  type HostIdentitySqlRuntime,
+} from "./identity-sql.ts";
+
 export {
   createOperatorInviteStore,
   createOperatorInvite,
@@ -250,7 +267,6 @@ export { invokeAs, type InvokeAsOptions } from "./invoke-as.ts";
 export {
   AUTH_TABLES,
   type ApiKeyRow,
-  type IdentityRow,
   type OperatorCredentialRow,
   type OperatorInviteRow,
   type OperatorRow,

package/src/auth/method-context.ts

@@ -8,6 +8,7 @@
 
 import type { PasswordHashOptions } from "../runtime/types.ts";
 import type { BreachCheckFn } from "./breach-check.ts";
+import type { IdentityStore } from "./identity.ts";
 import type { PasswordPolicyOptions } from "./password-policy.ts";
 import type { SessionStore } from "./sessions.ts";
 
@@ -15,6 +16,8 @@ import type { SessionStore } from "./sessions.ts";
 export interface ActiveGateAuthContext {
   readonly secret: string;
   readonly sessions: SessionStore;
+  /** Shared identity/credential store — method plugins resolve users here. */
+  readonly identities?: IdentityStore;
   readonly now?: () => number;
   /** From `gate.auth.passwordPolicy` — shared by credential method plugins. */
   readonly passwordPolicy?: PasswordPolicyOptions;

package/src/auth/oauth-as/cimd.ts

@@ -0,0 +1,132 @@
+/**
+ * CIMD (draft-ietf-oauth-client-id-metadata-document) client resolution —
+ * fetch the metadata document AT the `client_id` URL, validate it, and cache.
+ *
+ * This is a cache, not a DCR registry (locked decision 1): clients register
+ * nowhere; the document at their own HTTPS origin is the registration. The
+ * `client_id` host must differ from the AS issuer host so a client cannot
+ * self-host its metadata on the authorization server.
+ */
+
+import { OAuthError } from "./errors.ts";
+import type { ClientCacheRow, CimdClientMetadata } from "./tables.ts";
+
+/** Cache lifetime for fetched CIMD documents. */
+export const CIMD_CACHE_TTL_MS = 5 * 60_000;
+
+const REQUIRED_REDIRECT_SCHEMES = new Set(["https", "http"]);
+
+/**
+ * Validate a raw CIMD document against the URL it was fetched from.
+ *
+ * @param url - The `client_id` URL the document was served from
+ * @param raw - Parsed JSON body
+ */
+export function parseCimdMetadata(url: string, raw: unknown): CimdClientMetadata {
+  if (typeof raw !== "object" || raw === null) {
+    throw new OAuthError("invalid_request", "client metadata document is not an object");
+  }
+  const doc = raw as Record<string, unknown>;
+  const clientId = doc.client_id;
+  if (typeof clientId !== "string" || clientId !== url) {
+    throw new OAuthError("invalid_request", "metadata client_id must equal the document URL");
+  }
+  const redirectUris = doc.redirect_uris;
+  if (
+    !Array.isArray(redirectUris) ||
+    redirectUris.length === 0 ||
+    !redirectUris.every((u) => typeof u === "string" && isAcceptableRedirect(u))
+  ) {
+    throw new OAuthError(
+      "invalid_request",
+      "metadata redirect_uris must be absolute https/http URIs",
+    );
+  }
+  return {
+    client_id: clientId,
+    ...(typeof doc.client_name === "string" ? { client_name: doc.client_name } : {}),
+    redirect_uris: redirectUris as readonly string[],
+    ...(Array.isArray(doc.grant_types)
+      ? {
+          grant_types: (doc.grant_types as unknown[]).filter(
+            (g): g is string => typeof g === "string",
+          ),
+        }
+      : {}),
+    ...(Array.isArray(doc.response_types)
+      ? {
+          response_types: (doc.response_types as unknown[]).filter(
+            (r): r is string => typeof r === "string",
+          ),
+        }
+      : {}),
+    ...(typeof doc.token_endpoint_auth_method === "string"
+      ? { token_endpoint_auth_method: doc.token_endpoint_auth_method }
+      : {}),
+    ...(typeof doc.scope === "string" ? { scope: doc.scope } : {}),
+    ...(typeof doc.jwks_uri === "string" ? { jwks_uri: doc.jwks_uri } : {}),
+    ...(doc.jwks !== undefined ? { jwks: doc.jwks } : {}),
+  };
+}
+
+/**
+ * Resolve a `client_id` through the CIMD cache, refreshing when stale.
+ *
+ * @param cache - Cache map keyed by client id
+ * @param clientId - Must be an https URL
+ * @param now - Epoch-ms
+ * @param fetchDoc - Document loader (injectable for tests)
+ */
+export async function resolveCimdClient(
+  cache: Map<string, ClientCacheRow>,
+  clientId: string,
+  now: number,
+  fetchDoc: (url: string) => Promise<unknown> = defaultFetch,
+): Promise<ClientCacheRow> {
+  let parsed: URL;
+  try {
+    parsed = new URL(clientId);
+  } catch {
+    throw new OAuthError("invalid_request", "client_id must be an https URL");
+  }
+  if (parsed.protocol !== "https:") {
+    throw new OAuthError("invalid_request", "client_id must be an https URL");
+  }
+  const cached = cache.get(clientId);
+  if (cached && cached.deniedAt === null && cached.fetchedAt + CIMD_CACHE_TTL_MS > now) {
+    return cached;
+  }
+  let raw: unknown;
+  try {
+    raw = await fetchDoc(clientId);
+  } catch {
+    throw new OAuthError("invalid_request", "failed to fetch client metadata document");
+  }
+  const metadata = parseCimdMetadata(clientId, raw);
+  const row: ClientCacheRow = { clientId, metadata, fetchedAt: now, deniedAt: null };
+  cache.set(clientId, row);
+  return row;
+}
+
+function isAcceptableRedirect(uri: string): boolean {
+  let parsed: URL;
+  try {
+    parsed = new URL(uri);
+  } catch {
+    return false;
+  }
+  if (!REQUIRED_REDIRECT_SCHEMES.has(parsed.protocol.replace(":", ""))) return false;
+  // http is only acceptable on loopback (native/dev clients).
+  if (parsed.protocol === "http:" && !isLoopbackHost(parsed.hostname)) return false;
+  return true;
+}
+
+function isLoopbackHost(host: string): boolean {
+  return host === "localhost" || host === "127.0.0.1" || host === "[::1]" || host === "::1";
+}
+
+async function defaultFetch(url: string): Promise<unknown> {
+  const response = await fetch(url, { headers: { accept: "application/json" } });
+  if (!response.ok) throw new Error(`cimd fetch failed: ${response.status}`);
+  return (await response.json()) as unknown;
+}