@terrascale/sdk 0.0.2 → 0.0.4

package/src/local/router.js

@@ -1,8 +1,8 @@
+import { generateId } from "../ids.js";
 import {
   createHash,
   createHmac,
   randomBytes,
-  randomUUID,
   timingSafeEqual,
 } from "node:crypto";
 import {
@@ -18,7 +18,7 @@ import {
   encodeDatabaseValue,
   parseDatabaseJson,
   requireDatabaseU64,
-  requireDatabaseUuid,
+  requireDatabaseId,
 } from "../database-codec.js";
 import { matchesLocalBearerAuthorization } from "./authentication.js";
 import { jsonResponse, problemResponse } from "./context.js";
@@ -101,8 +101,8 @@ export class TerraScaleLocalRouter {
   constructor(store, scope, options) {
     this.#store = store;
     this.#scope = Object.freeze({
-      tenant: requireDatabaseUuid(scope.tenant),
-      database: requireDatabaseUuid(scope.database),
+      tenant: requireDatabaseId(scope.tenant),
+      database: requireDatabaseId(scope.database),
       shard: requireDatabaseU64(scope.shard),
     });
     this.#scopeKey = `${scope.tenant}/${scope.database}/${scope.shard}`;
@@ -112,7 +112,7 @@ export class TerraScaleLocalRouter {
     const writer = /** @type {{ readonly replica: string; readonly incarnation: string } | undefined} */ (
       store.getMeta(`native-writer:${this.#scopeKey}`)
     ) ?? {
-      replica: randomUUID(),
+      replica: generateId(),
       incarnation: randomBytes(16).toString("hex"),
     };
     this.#writer = Object.freeze(writer);
@@ -131,7 +131,7 @@ export class TerraScaleLocalRouter {
    * @returns {void}
    */
   bindCollection(binding) {
-    requireDatabaseUuid(binding.collection);
+    requireDatabaseId(binding.collection);
     requireDatabaseU64(binding.schema_generation, "schema generation", true);
     if (!/^[0-9a-f]{64}$/u.test(binding.schema_digest))
       throw new TypeError("Schema digest must be lowercase SHA256.");
@@ -170,8 +170,8 @@ export class TerraScaleLocalRouter {
           suffix,
         );
         if (match === null) return problemResponse(404, "unknown_route");
-        const collection = requireDatabaseUuid(match[1]);
-        const document = requireDatabaseUuid(match[2]);
+        const collection = requireDatabaseId(match[1]);
+        const document = requireDatabaseId(match[2]);
         return await this.#store.exclusive(() => {
           this.#binding(collection);
           return jsonResponse(this.#point(collection, document));
@@ -246,7 +246,7 @@ export class TerraScaleLocalRouter {
           suffix,
         );
       if (match === null) return problemResponse(404, "unknown_route");
-      const collection = requireDatabaseUuid(match[1]);
+      const collection = requireDatabaseId(match[1]);
       return await this.#store.exclusive(() => {
         this.#binding(collection);
         return this.#query(collection, match[2] === "subscriptions", raw);
@@ -599,7 +599,7 @@ export class TerraScaleLocalRouter {
     let id;
     let offset = 0;
     if (cursorValue === undefined) {
-      id = randomUUID();
+      id = generateId();
       const rows = /** @type {readonly { readonly scope: string; readonly id: string; readonly value: WirePoint }[]} */ (
         this.#store.listNamespace("native-points")
       )
@@ -812,10 +812,10 @@ function decodeCommit(raw) {
       if (!Array.isArray(write.observed))
         throw new TypeError("Invalid observed.");
       return {
-        collection: requireDatabaseUuid(write.collection),
+        collection: requireDatabaseId(write.collection),
         schema_generation: decimal(write.schema_generation),
         schema_digest: text(write.schema_digest),
-        document: requireDatabaseUuid(write.document),
+        document: requireDatabaseId(write.document),
         condition: /** @type {DatabaseCondition} */ (parsedCondition),
         observed: write.observed.map((rawObserved) => {
           const observed = object(rawObserved);

package/src/local/store.js

@@ -2,7 +2,7 @@ import { mkdirSync } from "node:fs";
 import { DatabaseSync } from "node:sqlite";
 import { dirname, isAbsolute } from "node:path";
 
-const SCHEMA_VERSION = 1;
+const FORMAT_VERSION = 2;
 
 /**
  * A small synchronous JSON record store for Node local adapters.
@@ -55,7 +55,7 @@ export class TerraScaleSqliteStore {
       if (databasePath !== ":memory:") {
         this.#database.exec("PRAGMA journal_mode = WAL;");
       }
-      this.#migrate();
+      this.#initialize();
     } catch (error) {
       this.#database.close();
       this.#closed = true;
@@ -128,6 +128,25 @@ export class TerraScaleSqliteStore {
     return rows.map((row) => /** @type {T} */ (parseJson(row.value, "record")));
   }
 
+  /**
+   * @template T
+   * @param {string} namespace
+   * @param {string} scope
+   * @returns {readonly { readonly id: string; readonly value: T }[]}
+   */
+  listEntries(namespace, scope) {
+    this.#assertOpen();
+    assertKey(namespace, "namespace");
+    assertKey(scope, "scope");
+    const rows = this.#database
+      .prepare("SELECT id, value FROM records WHERE namespace = ? AND scope = ? ORDER BY id ASC")
+      .all(namespace, scope);
+    return rows.map(row => ({
+      id: String(row.id),
+      value: /** @type {T} */ (parseJson(row.value, "record")),
+    }));
+  }
+
   /**
    * @template T
    * @param {string} namespace
@@ -339,32 +358,18 @@ export class TerraScaleSqliteStore {
   }
 
   /** @returns {void} */
-  #migrate() {
+  #initialize() {
     this.#database.exec("BEGIN IMMEDIATE;");
     try {
-      this.#database.exec(`
-        CREATE TABLE IF NOT EXISTS schema_migrations (
-          version INTEGER NOT NULL PRIMARY KEY,
-          applied_at TEXT NOT NULL
-        ) WITHOUT ROWID;
-      `);
-
-      const row = this.#database
-        .prepare(
-          "SELECT version FROM schema_migrations ORDER BY version DESC LIMIT 1",
-        )
-        .get();
-      const version = row?.version;
-      if (version !== undefined && typeof version !== "number") {
-        throw new Error("Invalid schema migration version.");
-      }
-      if (version !== undefined && version > SCHEMA_VERSION) {
+      const version = this.#database.prepare("PRAGMA user_version").get()?.user_version;
+      const table = this.#database.prepare("SELECT name FROM sqlite_schema WHERE type = 'table' AND name NOT LIKE 'sqlite_%' LIMIT 1").get();
+      if (version !== FORMAT_VERSION && !(version === 0 && table === undefined)) {
         throw new Error(
-          `Database schema version ${version} is newer than supported version ${SCHEMA_VERSION}.`,
+          `TS-754: unsupported local SQLite format. Stop the local runtime, delete ${this.databasePath} and its -wal/-shm files, then restart with fresh ULID storage.`,
         );
       }
 
-      if (version === undefined) {
+      if (version === 0) {
         this.#database.exec(`
           CREATE TABLE records (
             namespace TEXT NOT NULL,
@@ -379,11 +384,7 @@ export class TerraScaleSqliteStore {
             value TEXT NOT NULL CHECK (json_valid(value) = 1)
           ) WITHOUT ROWID;
         `);
-        this.#database
-          .prepare(
-            "INSERT INTO schema_migrations (version, applied_at) VALUES (?, ?)",
-          )
-          .run(SCHEMA_VERSION, new Date().toISOString());
+        this.#database.exec(`PRAGMA user_version = ${FORMAT_VERSION}`);
       }
       this.#database.exec("COMMIT;");
     } catch (error) {
@@ -406,7 +407,7 @@ export class TerraScaleSqliteStore {
         );
       }
     } catch {
-      // Preserve the original work/migration exception. SQLite will normally
+      // Preserve the original operation exception. SQLite will normally
       // have already rolled back a failed transaction automatically.
     }
   }

package/src/local/test-environment.js

@@ -1,3 +1,4 @@
+import { generateId } from "../ids.js";
 import { assertLocalSqliteEnvironment } from "./environment.js";
 /** Local development tests never relax CI/deployment/qualification guards. */
 export const localSqliteUnitTestsAllowed = (() => {
@@ -11,7 +12,7 @@ export const localSqliteUnitTestsAllowed = (() => {
 import { mkdtemp, rm } from "node:fs/promises";
 import { join } from "node:path";
 import { tmpdir } from "node:os";
-import { randomBytes, randomUUID } from "node:crypto";
+import { randomBytes } from "node:crypto";
 import { createTerraScaleSqliteRuntime } from "./index.js";
 /** @import { TerraScaleSqliteRuntimeOptions } from "./index.js" */
 /** @import { DatabaseCommit, DatabaseField, DatabasePoint } from "../database-types.js" */
@@ -25,7 +26,7 @@ export async function localFixture(options = {}) {
     ...options,
     sqlite: { enabled: true, databasePath },
   });
-  const collection = randomUUID();
+  const collection = generateId();
   const binding = {
     collection,
     schema_generation: 1n,

package/src/postgres.js

@@ -1,3 +1,4 @@
+import { isValidId } from "./ids.js";
 /** @deprecated The C# TerraBase has no PostgreSQL listener.
  * Node-only PostgreSQL client for the signed INT8/TEXT point SQL listener. */
 import { lookup } from "node:dns/promises";
@@ -38,8 +39,8 @@ const MAX_INT8 = (1n << 63n) - 1n;
  *   readonly port: number;
  *   readonly tlsServerName: string;
  *   readonly caCertificatePem: string;
- *   readonly database: string;
- *   readonly keyId: string;
+ *   readonly database: import("./ids.js").EntityId;
+ *   readonly keyId: import("./ids.js").EntityId;
  *   readonly password: string;
  *   readonly connectTimeoutMs?: number;
  * }} PostgresConfig
@@ -168,8 +169,8 @@ function configuration(config) {
     !Number.isInteger(timeout) ||
     timeout < 1 ||
     timeout > 10000 ||
-    !/^[0-9a-f]{8}(?:-[0-9a-f]{4}){3}-[0-9a-f]{12}$/.test(config.database) ||
-    !canonicalBase64(config.keyId, 16) ||
+    !isValidId(config.database) ||
+    !isValidId(config.keyId) ||
     parts.length !== 3 ||
     parts[0] !== "tbk1" ||
     parts[1] !== config.keyId ||

package/src/react/core.js

@@ -1,3 +1,4 @@
+import { generateId } from "../ids.js";
 /** @import { TerraScaleError, TerraScaleResult } from "../result.js" */
 /** @import { DatabaseResult } from "../database-types.js" */
 
@@ -733,8 +734,7 @@ function normalizeIdempotencyKey(value) {
 
 /** @returns {string} */
 function createIdempotencyKey() {
-  const randomUuid = globalThis.crypto?.randomUUID;
-  return randomUuid === undefined ? `tsm-${Date.now().toString(36)}-${Math.random().toString(36).slice(2)}` : randomUuid.call(globalThis.crypto);
+  return generateId();
 }
 
 /** @returns {ReactiveMutationError} */

package/src/ts-auth-ids.js

@@ -0,0 +1,122 @@
+import { requireId } from "./ids.js";
+
+const singleEntityRoutes = new Set([
+  "tsauth.users.get", "tsauth.users.create", "tsauth.users.update",
+  "tsauth.apiKeys.create",
+  "tsauth.organizations.get", "tsauth.organizations.create", "tsauth.organizations.update",
+  "tsauth.organizations.createMembership", "tsauth.organizations.updateMembership",
+  "tsauth.organizations.createInvitation", "tsauth.organizations.revokeInvitation", "tsauth.organizations.createDomain",
+  "tsauth.connections.create", "tsauth.connections.update",
+  "tsauth.directories.create", "tsauth.directories.rotate",
+  "tsauth.jwtTemplates.create", "tsauth.jwtTemplates.update",
+  "tsauth.webhooks.create",
+  "tsauth.instance.get", "tsauth.instance.update",
+]);
+
+const requiredRootReferences = new Map([
+  ["tsauth.oidc.userinfo", "sub"],
+  ["tsauth.organizations.enrollDomain", "org_id"],
+]);
+
+/** @type {ReadonlyMap<string, readonly string[]>} */
+const entityReferenceFields = new Map([
+  ["tsauth.organizations.createMembership", ["organization_id", "user_id"]],
+  ["tsauth.organizations.updateMembership", ["organization_id", "user_id"]],
+  ["tsauth.organizations.listMemberships", ["organization_id", "user_id"]],
+  ["tsauth.organizations.createInvitation", ["organization_id"]],
+  ["tsauth.organizations.revokeInvitation", ["organization_id"]],
+  ["tsauth.organizations.listInvitations", ["organization_id"]],
+  ["tsauth.organizations.createDomain", ["organization_id"]],
+  ["tsauth.organizations.listDomains", ["organization_id"]],
+  ["tsauth.auditEvents.list", ["instance_id"]],
+  ["tsauth.webhooks.deadLetter", ["endpoint_id", "event_id"]],
+  ["tsauth.oauthClients.create", ["client_id"]],
+  ["tsauth.oauthClients.update", ["client_id"]],
+  ["tsauth.oauthClients.list", ["client_id"]],
+  ["tsauth.oauthResources.create", ["introspection_client_id"]],
+  ["tsauth.oauthResources.update", ["introspection_client_id"]],
+  ["tsauth.oauthResources.list", ["introspection_client_id"]],
+  ["tsauth.connections.create", ["org_id"]],
+  ["tsauth.connections.update", ["org_id"]],
+  ["tsauth.connections.list", ["org_id"]],
+  ["tsauth.directories.create", ["org_id"]],
+  ["tsauth.directories.rotate", ["org_id"]],
+  ["tsauth.directories.list", ["org_id"]],
+]);
+
+/**
+ * Validate the documented endpointId:eventId delivery selector.
+ * @param {unknown} value
+ * @returns {string}
+ */
+export function requireDeadLetterId(value) {
+  if (typeof value !== "string" || value.split(":").length !== 2)
+    throw new TypeError("Dead-letter selector must contain endpoint and event ULIDs separated by a colon.");
+  const [endpoint, event] = value.split(":");
+  requireId(endpoint, "endpoint id");
+  requireId(event, "event id");
+  return value;
+}
+
+/**
+ * Validate identity fields in the hosted-auth DTOs without inspecting customer metadata.
+ * @param {unknown} value
+ * @param {string} route
+ * @param {boolean} [entity]
+ * @returns {void}
+ */
+export function validateTsAuthIds(value, route, entity = singleEntityRoutes.has(route)) {
+  const requiredReference = requiredRootReferences.get(route);
+  if ((entity || requiredReference !== undefined) && (typeof value !== "object" || value === null || Array.isArray(value)))
+    throw new TypeError("Hosted-auth response must be an object with its required ULID.");
+  if (Array.isArray(value)) {
+    if (route === "tsauth.users.regenerateRecoveryCodes") {
+      if (!value.every(code => typeof code === "string"))
+        throw new TypeError("Recovery codes must be strings.");
+      return;
+    }
+    for (const entry of value) validateTsAuthIds(entry, route, true);
+    return;
+  }
+  if (typeof value !== "object" || value === null) return;
+  if (requiredReference !== undefined) requireId(Reflect.get(value, requiredReference), requiredReference);
+  const deadLetter = route === "tsauth.webhooks.deadLetter";
+  if (entity) {
+    if (deadLetter) requireDeadLetterId(Reflect.get(value, "id"));
+    else requireId(Reflect.get(value, "id"), "entity id");
+  }
+  const fields = ["id", "user_id", "organization_id", "org_id", "endpoint_id", "event_id", "instance_id", "actor_id"];
+  const nullableOrgId = route.startsWith("tsauth.connections.") || route.startsWith("tsauth.directories.");
+  if (/^tsauth\.(oauthClients|oauthResources|oidc)\./u.test(route))
+    fields.push("client_id", "introspection_client_id", "sub", "sid", "jti");
+  const requiredFields = entityReferenceFields.get(route) ?? [];
+  const validateReferences = entity || Object.hasOwn(value, "id");
+  for (const field of fields) {
+    if (Object.hasOwn(value, field) || (validateReferences && requiredFields.includes(field))) {
+      const id = Reflect.get(value, field);
+      if (field === "id" && deadLetter) requireDeadLetterId(id);
+      else if (id !== null || !(field === "sid" || (field === "org_id" && nullableOrgId))) requireId(id, field);
+    }
+  }
+  // `data` objects in audit events are customer payloads; only page arrays contain DTOs.
+  if (Object.hasOwn(value, "data") && Array.isArray(Reflect.get(value, "data")))
+    validateTsAuthIds(Reflect.get(value, "data"), route);
+  for (const field of ["passkeys", "clients", "resources"])
+    if (Object.hasOwn(value, field)) validateTsAuthIds(Reflect.get(value, field), route);
+  for (const field of ["organization", "user"]) {
+    if (Object.hasOwn(value, field) && Reflect.get(value, field) !== null) {
+      const relatedRoute = field === "organization" ? "tsauth.organizations.get" : "tsauth.users.get";
+      validateTsAuthIds(Reflect.get(value, field), relatedRoute, true);
+    }
+  }
+  let oauthEntity;
+  if (route.startsWith("tsauth.oauthClients.")) oauthEntity = "client";
+  else if (route.startsWith("tsauth.oauthResources.")) oauthEntity = "resource";
+  if (oauthEntity !== undefined && Object.hasOwn(value, oauthEntity))
+    validateTsAuthIds(Reflect.get(value, oauthEntity), route, true);
+  if (Object.hasOwn(value, "allowed_client_ids")) {
+    const ids = Reflect.get(value, "allowed_client_ids");
+    if (!Array.isArray(ids)) throw new TypeError("allowed_client_ids must be an array of ULIDs.");
+    for (const id of ids) requireId(id, "allowed_client_ids");
+  }
+}