@jxsuite/connector 0.1.0

package/src/types.ts

@@ -0,0 +1,139 @@
+/**
+ * Connector contract types (specs/extensions.md §11–§12, plan Part 4a).
+ *
+ * These are the shapes the connector publishes for its dependents: the auth extension implements
+ * `JxAuthHooks` against `AuthorizeInput`/`AuthorizeDecision`, server hosts share one
+ * `JxServerContext` across ordered mounts, and every module in this package speaks the table /
+ * connection definitions declared in project.json's `data` and `connections` sections.
+ */
+
+// ─── Field / table schema ─────────────────────────────────────────────────────
+
+/**
+ * A column field schema — the JSON-Schema subset published as the core field union
+ * (`JxFieldSchema`) plus the relationship-ref form (`{ $ref: "#/<section>/<name>" }`,
+ * specs/relationships.md §1). Plain JxFieldSchema + RelationshipRef cover columns v1; the connector
+ * ships no field-union extras.
+ */
+export interface ColumnFieldSchema {
+  type?: "string" | "number" | "integer" | "boolean" | "array" | "object";
+  /** Relationship reference: "#/<sectionKey>/<entryName>". */
+  $ref?: string;
+  items?: ColumnFieldSchema;
+  properties?: Record<string, ColumnFieldSchema>;
+  required?: string[];
+  enum?: unknown[];
+  format?: string;
+  default?: unknown;
+  description?: string;
+}
+
+/** The `schema` block of a table definition. */
+export interface TableSchema {
+  type?: "object";
+  properties?: Record<string, ColumnFieldSchema>;
+  required?: string[];
+}
+
+/** One entry of the project.json `data` section. */
+export interface TableDef {
+  connection: string;
+  schema: TableSchema;
+  id?: "uuid" | "integer";
+  timestamps?: boolean;
+  indexes?: (string | string[])[];
+  permissions?: TablePermissions;
+  ownerField?: string;
+}
+
+/** One entry of the project.json `connections` section (identifiers only — never secrets). */
+export interface ConnectionDef {
+  provider: string;
+  binding?: string;
+  databaseId?: string;
+  accountId?: string;
+  urlEnv?: string;
+  hyperdriveId?: string;
+  file?: string;
+  /** Connection name, injected by hosts when passing the def to connector capabilities. */
+  $name?: string;
+  [key: string]: unknown;
+}
+
+// ─── Permissions ──────────────────────────────────────────────────────────────
+
+export type PermissionAction = "read" | "insert" | "update" | "delete";
+
+/** Access rule: `role:<r>` grants the named role (evaluated by the auth extension). */
+export type PermissionRule = "public" | "none" | "authenticated" | "owner" | `role:${string}`;
+
+export type TablePermissions = Partial<Record<PermissionAction, PermissionRule>>;
+
+/** Default rules when a table declares none: reads are public, writes are closed. */
+export const DEFAULT_PERMISSIONS: Record<PermissionAction, PermissionRule> = {
+  delete: "none",
+  insert: "none",
+  read: "public",
+  update: "none",
+};
+
+// ─── Auth contract (implemented by @jxsuite/auth in Part 4b) ─────────────────
+
+/** The session shape auth hooks resolve from a request. */
+export interface SessionInfo {
+  userId: string;
+  role?: string;
+  /** Full user record, when the auth provider exposes one. */
+  user?: Record<string, unknown>;
+  [key: string]: unknown;
+}
+
+export interface AuthorizeInput {
+  table: string;
+  action: PermissionAction;
+  rule: PermissionRule;
+  session: SessionInfo | null;
+  ownerField?: string;
+}
+
+export interface AuthorizeDecision {
+  allow: boolean;
+  /** HTTP status for a denial (401 unauthenticated, 403 forbidden). */
+  status?: number;
+  error?: string;
+  /** Columns forced onto insert/update payloads (e.g. the owner id). */
+  setColumns?: Record<string, unknown>;
+  /** Row filter scoping reads/writes to the owner: `WHERE <field> = <value>`. */
+  whereOwner?: { field: string; value: unknown } | null;
+}
+
+/** The hooks an auth mount publishes on the shared server context. */
+export interface JxAuthHooks {
+  getSession: (request: Request, env: Record<string, unknown>) => Promise<SessionInfo | null>;
+  authorize: (input: AuthorizeInput, env: Record<string, unknown>) => Promise<AuthorizeDecision>;
+}
+
+/**
+ * One shared mutable context per worker isolate, passed to every mount in `server.order`
+ * (specs/extensions.md §11). The auth mount (order 10) sets `auth`; the data mount (order 20)
+ * consumes it and fails closed when it is absent.
+ */
+export interface JxServerContext {
+  auth?: JxAuthHooks;
+  [key: string]: unknown;
+}
+
+// ─── Deploy / dialect capability results ─────────────────────────────────────
+
+/** Result shape of the `deploySchema` connector capability. */
+export interface DeploySchemaResult {
+  statements: string[];
+  applied: boolean;
+  warnings: string[];
+}
+
+/** Result shape of the `testConnection` connector capability. */
+export interface TestConnectionResult {
+  ok: boolean;
+  error?: string;
+}

package/src/validate.ts

@@ -0,0 +1,193 @@
+/**
+ * Validate — hand-rolled row validation against a table's column schema.
+ *
+ * Deliberately not ajv: ajv compiles validators with `new Function`, which Workers forbid. The
+ * grammar here is the small field-schema subset tables actually use (scalar types, arrays, objects,
+ * enums, relationship refs), plus payload-level rules: unknown and read-only fields are rejected,
+ * required fields are enforced on full (insert) validation, and form-shaped string values are
+ * coerced to their declared column types ("42" → 42, "true" → true) so plain FormData submissions
+ * validate cleanly.
+ */
+
+import { parseRefPointer } from "./columns.ts";
+import type { ColumnFieldSchema, TableDef } from "./types.ts";
+
+export interface ValidationIssue {
+  field: string;
+  message: string;
+}
+
+export interface ValidationResult {
+  valid: boolean;
+  errors: ValidationIssue[];
+  /** The coerced payload (schema-typed values), keyed by schema field name. */
+  value: Record<string, unknown>;
+}
+
+/** Columns the data mount owns; clients may never write them. */
+const READ_ONLY_FIELDS = new Set(["id", "created_at", "updated_at"]);
+
+/**
+ * Validate (and coerce) a row payload against a table definition.
+ *
+ * @param {TableDef} table - The table definition from the `data` section
+ * @param {unknown} payload - Parsed request body
+ * @param {{ partial?: boolean }} [options] - `partial` skips required-field checks (PATCH)
+ * @returns {ValidationResult}
+ */
+export function validateRow(
+  table: TableDef,
+  payload: unknown,
+  options: { partial?: boolean } = {},
+): ValidationResult {
+  const { partial = false } = options;
+  const errors: ValidationIssue[] = [];
+  const value: Record<string, unknown> = {};
+
+  if (payload === null || typeof payload !== "object" || Array.isArray(payload)) {
+    return { errors: [{ field: "", message: "Body must be a JSON object" }], valid: false, value };
+  }
+  const body = payload as Record<string, unknown>;
+  const fields = table.schema.properties ?? {};
+
+  for (const [key, raw] of Object.entries(body)) {
+    if (READ_ONLY_FIELDS.has(key)) {
+      errors.push({ field: key, message: "Read-only field" });
+      continue;
+    }
+    const schema = fields[key];
+    if (!schema) {
+      errors.push({ field: key, message: "Unknown field" });
+      continue;
+    }
+    const coerced = coerceField(key, schema, raw, errors);
+    if (coerced !== INVALID) {
+      value[key] = coerced;
+    }
+  }
+
+  if (!partial) {
+    for (const required of table.schema.required ?? []) {
+      if (body[required] === undefined) {
+        errors.push({ field: required, message: "Required field is missing" });
+      }
+    }
+  }
+
+  return { errors, valid: errors.length === 0, value };
+}
+
+/** Sentinel distinguishing "coercion failed" from a legitimate undefined/null value. */
+const INVALID = Symbol("invalid");
+
+/**
+ * Coerce one payload value against its field schema, appending errors on mismatch.
+ *
+ * @param {string} field
+ * @param {ColumnFieldSchema} schema
+ * @param {unknown} raw
+ * @param {ValidationIssue[]} errors
+ * @returns {unknown} The coerced value, or the INVALID sentinel
+ */
+function coerceField(
+  field: string,
+  schema: ColumnFieldSchema,
+  raw: unknown,
+  errors: ValidationIssue[],
+): unknown {
+  if (raw === null || raw === undefined) {
+    return null;
+  }
+
+  const toOne = parseRefPointer(schema.$ref);
+  if (toOne) {
+    if (typeof raw !== "string" || raw === "") {
+      errors.push({ field, message: "Reference value must be an entry id string" });
+      return INVALID;
+    }
+    return raw;
+  }
+
+  const itemsRef = schema.type === "array" ? parseRefPointer(schema.items?.$ref) : null;
+  if (itemsRef) {
+    const list = parseMaybeJson(raw);
+    if (!Array.isArray(list) || list.some((item) => typeof item !== "string" || item === "")) {
+      errors.push({ field, message: "Reference list must be an array of entry id strings" });
+      return INVALID;
+    }
+    return list;
+  }
+
+  const coerced = coerceScalar(schema, raw);
+  if (coerced === INVALID) {
+    errors.push({ field, message: `Expected ${schema.type ?? "string"}` });
+    return INVALID;
+  }
+  if (schema.enum && !schema.enum.some((allowed) => allowed === coerced)) {
+    errors.push({ field, message: "Value is not one of the allowed choices" });
+    return INVALID;
+  }
+  return coerced;
+}
+
+/** Coerce a scalar payload value to its schema type, or INVALID. */
+function coerceScalar(schema: ColumnFieldSchema, raw: unknown): unknown {
+  switch (schema.type) {
+    case "number":
+    case "integer": {
+      let num: number;
+      if (typeof raw === "number") {
+        num = raw;
+      } else if (typeof raw === "string" && raw.trim() !== "" && !Number.isNaN(Number(raw))) {
+        num = Number(raw);
+      } else {
+        return INVALID;
+      }
+      if (schema.type === "integer" && !Number.isInteger(num)) {
+        return INVALID;
+      }
+      return num;
+    }
+    case "boolean": {
+      if (typeof raw === "boolean") {
+        return raw;
+      }
+      if (raw === "true" || raw === "on" || raw === "1" || raw === 1) {
+        return true;
+      }
+      if (raw === "false" || raw === "off" || raw === "0" || raw === 0 || raw === "") {
+        return false;
+      }
+      return INVALID;
+    }
+    case "array": {
+      const parsed = parseMaybeJson(raw);
+      return Array.isArray(parsed) ? parsed : INVALID;
+    }
+    case "object": {
+      const parsed = parseMaybeJson(raw);
+      return parsed !== null && typeof parsed === "object" && !Array.isArray(parsed)
+        ? parsed
+        : INVALID;
+    }
+    default: {
+      return typeof raw === "string" ? raw : INVALID;
+    }
+  }
+}
+
+/** Parse JSON-looking strings (FormData carries arrays/objects as text); pass everything else. */
+function parseMaybeJson(raw: unknown): unknown {
+  if (typeof raw !== "string") {
+    return raw;
+  }
+  const text = raw.trim();
+  if (!text.startsWith("[") && !text.startsWith("{")) {
+    return raw;
+  }
+  try {
+    return JSON.parse(text) as unknown;
+  } catch {
+    return raw;
+  }
+}