@openlup/platform 0.15.0 → 0.17.0

package/sql/20260901143000_admin_membership_authority_foundation.sql

@@ -0,0 +1,234 @@
+-- Dormant direct human membership authority.
+--
+-- This forward introduces a provider-neutral human principal and its separate
+-- current-panel membership for the direct bundle. It mirrors the managed role,
+-- active/revoked state, provenance, acceptance, revocation, retained identity,
+-- last-human-administrator refusal, and one-row revoke audit semantics. It does
+-- not verify a login, grant browser access, seed a person, or link to the
+-- existing platform_control_operators machine authority. The direct host owns
+-- activation of a future human-login adapter; until then these relations are
+-- deliberately dormant and default-deny for the actor roles.
+
+CREATE TABLE public.platform_human_principals (
+  principal_id uuid PRIMARY KEY,
+  email text NOT NULL UNIQUE,
+  created_at timestamptz NOT NULL DEFAULT now()
+);
+
+CREATE TABLE public.platform_human_memberships (
+  principal_id uuid PRIMARY KEY REFERENCES public.platform_human_principals(principal_id) ON DELETE RESTRICT,
+  role text NOT NULL CHECK (role IN ('admin', 'distributor')),
+  membership_state text NOT NULL CHECK (membership_state IN ('active', 'revoked')),
+  membership_provenance text NOT NULL CHECK (membership_provenance IN ('legacy', 'invitation')),
+  membership_accepted_at timestamptz NOT NULL,
+  membership_revoked_at timestamptz,
+  membership_revoked_by uuid REFERENCES public.platform_human_principals(principal_id) ON DELETE RESTRICT,
+  membership_revocation_reason text,
+  CONSTRAINT platform_human_memberships_lifecycle_check CHECK (
+    (membership_state = 'active'
+      AND membership_revoked_at IS NULL
+      AND membership_revoked_by IS NULL
+      AND membership_revocation_reason IS NULL)
+    OR
+    (membership_state = 'revoked'
+      AND membership_revoked_at IS NOT NULL
+      AND membership_revoked_by IS NOT NULL)
+  ),
+  CONSTRAINT platform_human_memberships_distinct_revoker_check
+    CHECK (membership_revoked_by IS NULL OR membership_revoked_by <> principal_id),
+  CONSTRAINT platform_human_memberships_reason_length_check
+    CHECK (membership_revocation_reason IS NULL OR char_length(membership_revocation_reason) <= 1000)
+);
+
+CREATE TABLE public.platform_human_membership_audit_events (
+  id uuid PRIMARY KEY DEFAULT gen_random_uuid(),
+  actor_principal_id uuid NOT NULL REFERENCES public.platform_human_principals(principal_id) ON DELETE RESTRICT,
+  target_principal_id uuid NOT NULL REFERENCES public.platform_human_principals(principal_id) ON DELETE RESTRICT,
+  action text NOT NULL CHECK (action = 'revoke'),
+  old_value jsonb NOT NULL,
+  new_value jsonb NOT NULL,
+  reason text,
+  occurred_at timestamptz NOT NULL DEFAULT now()
+);
+
+CREATE INDEX platform_human_membership_audit_target_idx
+  ON public.platform_human_membership_audit_events(target_principal_id, occurred_at DESC);
+
+REVOKE ALL ON TABLE
+  public.platform_human_principals,
+  public.platform_human_memberships,
+  public.platform_human_membership_audit_events
+FROM PUBLIC, anon, authenticated;
+
+CREATE FUNCTION public.platform_human_membership_is_active(p_principal_id uuid)
+RETURNS boolean
+LANGUAGE sql
+STABLE
+SET search_path = pg_catalog
+AS $$
+  SELECT EXISTS (
+    SELECT 1
+    FROM public.platform_human_memberships AS membership_row
+    WHERE membership_row.principal_id = p_principal_id
+      AND membership_row.membership_state = 'active'
+  );
+$$;
+
+CREATE FUNCTION public.platform_human_membership_is_administrator(p_principal_id uuid)
+RETURNS boolean
+LANGUAGE sql
+STABLE
+SET search_path = pg_catalog
+AS $$
+  SELECT EXISTS (
+    SELECT 1
+    FROM public.platform_human_memberships AS membership_row
+    WHERE membership_row.principal_id = p_principal_id
+      AND membership_row.membership_state = 'active'
+      AND membership_row.role = 'admin'
+  );
+$$;
+
+CREATE FUNCTION public.platform_human_memberships_guard()
+RETURNS trigger
+LANGUAGE plpgsql
+SET search_path = pg_catalog, public
+AS $$
+DECLARE
+  v_removes_active_human_admin boolean := false;
+  v_other_active_human_admins integer;
+BEGIN
+  IF TG_OP = 'DELETE' THEN
+    v_removes_active_human_admin := OLD.membership_state = 'active' AND OLD.role = 'admin';
+  ELSE
+    IF (OLD.membership_state, OLD.membership_provenance, OLD.membership_accepted_at,
+        OLD.membership_revoked_at, OLD.membership_revoked_by,
+        OLD.membership_revocation_reason)
+       IS DISTINCT FROM
+       (NEW.membership_state, NEW.membership_provenance, NEW.membership_accepted_at,
+        NEW.membership_revoked_at, NEW.membership_revoked_by,
+        NEW.membership_revocation_reason)
+      AND current_setting('app.platform_human_membership_revoke', true) IS DISTINCT FROM 'true' THEN
+      RAISE EXCEPTION 'platform_human_membership_lifecycle_update_forbidden' USING ERRCODE = '42501';
+    END IF;
+
+    IF OLD.membership_state <> 'active' AND NEW.role IS DISTINCT FROM OLD.role THEN
+      RAISE EXCEPTION 'platform_human_target_membership_inactive' USING ERRCODE = 'P0001';
+    END IF;
+
+    v_removes_active_human_admin := OLD.membership_state = 'active'
+      AND OLD.role = 'admin'
+      AND (NEW.membership_state <> 'active' OR NEW.role <> 'admin');
+  END IF;
+
+  IF v_removes_active_human_admin THEN
+    PERFORM pg_advisory_xact_lock(hashtext('platform_human_memberships_active_admin')::bigint);
+    SELECT count(*)
+      INTO v_other_active_human_admins
+    FROM public.platform_human_memberships
+    WHERE principal_id <> OLD.principal_id
+      AND membership_state = 'active'
+      AND role = 'admin';
+
+    IF v_other_active_human_admins < 1 THEN
+      RAISE EXCEPTION 'platform_human_last_admin_lockout' USING ERRCODE = 'P0001';
+    END IF;
+  END IF;
+
+  IF TG_OP = 'DELETE' THEN
+    RAISE EXCEPTION 'platform_human_membership_delete_forbidden' USING ERRCODE = '42501';
+  END IF;
+
+  RETURN NEW;
+END;
+$$;
+
+CREATE TRIGGER trg_platform_human_memberships_guard
+  BEFORE UPDATE OR DELETE ON public.platform_human_memberships
+  FOR EACH ROW EXECUTE FUNCTION public.platform_human_memberships_guard();
+
+CREATE FUNCTION public.platform_revoke_human_membership(
+  p_actor_principal_id uuid,
+  p_target_principal_id uuid,
+  p_reason text DEFAULT NULL
+)
+RETURNS public.platform_human_memberships
+LANGUAGE plpgsql
+SET search_path = pg_catalog, public
+AS $$
+DECLARE
+  v_target public.platform_human_memberships;
+  v_reason text := NULLIF(btrim(p_reason), '');
+  v_revoked_at timestamptz := clock_timestamp();
+BEGIN
+  IF NOT public.platform_human_membership_is_administrator(p_actor_principal_id) THEN
+    RAISE EXCEPTION 'platform_human_revoke_forbidden' USING ERRCODE = '42501';
+  END IF;
+
+  IF p_target_principal_id IS NULL THEN
+    RAISE EXCEPTION 'platform_human_target_required' USING ERRCODE = '22023';
+  END IF;
+
+  IF p_target_principal_id = p_actor_principal_id THEN
+    RAISE EXCEPTION 'platform_human_self_revoke_forbidden' USING ERRCODE = 'P0001';
+  END IF;
+
+  IF v_reason IS NOT NULL AND char_length(v_reason) > 1000 THEN
+    RAISE EXCEPTION 'platform_human_revocation_reason_too_long' USING ERRCODE = '22023';
+  END IF;
+
+  SELECT * INTO v_target
+  FROM public.platform_human_memberships
+  WHERE principal_id = p_target_principal_id
+  FOR UPDATE;
+
+  IF NOT FOUND THEN
+    RAISE EXCEPTION 'platform_human_target_not_found' USING ERRCODE = 'P0002';
+  END IF;
+
+  IF v_target.membership_state = 'revoked' THEN
+    RETURN v_target;
+  END IF;
+
+  PERFORM set_config('app.platform_human_membership_revoke', 'true', true);
+
+  UPDATE public.platform_human_memberships
+  SET membership_state = 'revoked',
+      membership_revoked_at = v_revoked_at,
+      membership_revoked_by = p_actor_principal_id,
+      membership_revocation_reason = v_reason
+  WHERE principal_id = p_target_principal_id
+  RETURNING * INTO v_target;
+
+  INSERT INTO public.platform_human_membership_audit_events
+    (actor_principal_id, target_principal_id, action, old_value, new_value, reason, occurred_at)
+  VALUES (
+    p_actor_principal_id,
+    p_target_principal_id,
+    'revoke',
+    jsonb_build_object('membershipState', 'active', 'role', v_target.role),
+    jsonb_build_object(
+      'membershipState', 'revoked',
+      'revokedAt', v_revoked_at,
+      'revokedBy', p_actor_principal_id,
+      'revocationReason', v_reason
+    ),
+    v_reason,
+    v_revoked_at
+  );
+
+  RETURN v_target;
+END;
+$$;
+
+REVOKE ALL ON FUNCTION public.platform_human_membership_is_active(uuid)
+  FROM PUBLIC, anon, authenticated;
+REVOKE ALL ON FUNCTION public.platform_human_membership_is_administrator(uuid)
+  FROM PUBLIC, anon, authenticated;
+REVOKE ALL ON FUNCTION public.platform_human_memberships_guard()
+  FROM PUBLIC, anon, authenticated;
+REVOKE ALL ON FUNCTION public.platform_revoke_human_membership(uuid, uuid, text)
+  FROM PUBLIC, anon, authenticated;
+
+COMMENT ON FUNCTION public.platform_revoke_human_membership(uuid, uuid, text) IS
+  'Dormant direct-bundle revoke command. Requires an active human administrator, retains the target principal/membership, refuses self and last-admin removal, and records one atomic revoke event.';

package/sql/20261018120000_identity_operator_invitations.sql

@@ -0,0 +1,42 @@
+-- Pending direct operator invitations. Lifecycle commands use the trusted
+-- server transaction lane; this forward adds no function or actor privilege.
+CREATE TABLE public.identity_operator_invitations (
+  principal_id uuid PRIMARY KEY REFERENCES public.platform_human_principals(principal_id),
+  invitation_id uuid NOT NULL UNIQUE,
+  email_key text NOT NULL UNIQUE,
+  role text NOT NULL CHECK (role IN ('admin', 'distributor')),
+  phase text NOT NULL CHECK (phase IN ('invited', 'accepted', 'expired', 'cancelled')),
+  invited_by uuid NOT NULL REFERENCES public.platform_human_principals(principal_id),
+  invited_at timestamptz NOT NULL,
+  expires_at timestamptz NOT NULL,
+  accepted_at timestamptz,
+  closed_at timestamptz,
+  CHECK (email_key = lower(btrim(email_key)) AND NOT email_key = ''),
+  CHECK (expires_at BETWEEN invited_at + interval '60 seconds' AND invited_at + interval '30 days'),
+  CHECK (
+    (phase = 'invited' AND accepted_at IS NULL AND closed_at IS NULL)
+    OR (phase = 'accepted' AND accepted_at IS NOT NULL
+      AND accepted_at BETWEEN invited_at AND expires_at
+      AND NOT accepted_at = expires_at AND closed_at = accepted_at)
+    OR (phase = 'expired' AND accepted_at IS NULL AND closed_at = expires_at)
+    OR (phase = 'cancelled' AND accepted_at IS NULL AND closed_at IS NOT NULL)
+  )
+);
+
+CREATE TABLE public.identity_operator_invitation_events (
+  event_id uuid PRIMARY KEY,
+  invitation_id uuid NOT NULL,
+  principal_id uuid NOT NULL REFERENCES public.platform_human_principals(principal_id),
+  action text NOT NULL CHECK (action IN ('issue', 'reissue', 'accept', 'expire', 'cancel')),
+  actor_kind text NOT NULL CHECK (actor_kind IN ('human', 'system')),
+  actor_principal_id uuid REFERENCES public.platform_human_principals(principal_id),
+  old_value jsonb NOT NULL,
+  new_value jsonb NOT NULL,
+  occurred_at timestamptz NOT NULL,
+  UNIQUE (invitation_id, action),
+  CHECK ((actor_kind = 'human' AND actor_principal_id IS NOT NULL)
+    OR (actor_kind = 'system' AND actor_principal_id IS NULL))
+);
+
+CREATE INDEX identity_operator_invitation_events_target_idx
+  ON public.identity_operator_invitation_events(principal_id, occurred_at DESC);

package/sql/20261018180000_identity_operator_challenges.sql

@@ -0,0 +1,56 @@
+CREATE UNIQUE INDEX platform_human_principals_normalized_email_key
+  ON public.platform_human_principals (lower(btrim(email)));
+
+CREATE TABLE public.operator_identity_challenges (
+  id uuid PRIMARY KEY DEFAULT gen_random_uuid(),
+  principal_id uuid NOT NULL
+    REFERENCES public.platform_human_principals(principal_id),
+  email_fingerprint text NOT NULL,
+  token_hash text NOT NULL,
+  created_at timestamptz NOT NULL DEFAULT now(),
+  expires_at timestamptz NOT NULL,
+  used_at timestamptz,
+
+  CONSTRAINT operator_identity_challenges_email_fingerprint_check
+    CHECK (
+      length(email_fingerprint) = 64
+      AND translate(
+        email_fingerprint,
+        '0123456789abcdef',
+        ''
+      ) = ''
+    ),
+
+  CONSTRAINT operator_identity_challenges_token_hash_check
+    CHECK (
+      length(token_hash) = 64
+      AND translate(
+        token_hash,
+        '0123456789abcdef',
+        ''
+      ) = ''
+    ),
+
+  CONSTRAINT operator_identity_challenges_token_hash_key
+    UNIQUE (token_hash),
+
+  CONSTRAINT operator_identity_challenges_expiry_check
+    CHECK (
+      expires_at BETWEEN
+        created_at + INTERVAL '1 second'
+        AND created_at + INTERVAL '10 minutes'
+    ),
+
+  CONSTRAINT operator_identity_challenges_used_at_check
+    CHECK (
+      used_at IS NULL
+      OR used_at BETWEEN created_at AND expires_at
+    )
+);
+
+CREATE INDEX operator_identity_challenges_principal_created_idx
+  ON public.operator_identity_challenges
+    (principal_id, created_at DESC);
+
+CREATE INDEX operator_identity_challenges_expiry_idx
+  ON public.operator_identity_challenges (expires_at, id);

package/sql/20261018190000_identity_privacy_erasures.sql

@@ -0,0 +1,15 @@
+-- Direct identity erasure receipts. Audit and idempotency share one retained
+-- pseudonymous record; no personal export snapshot or actor grants are stored.
+CREATE TABLE public.identity_privacy_erasures (
+  erasure_id uuid PRIMARY KEY,
+  idempotency_key uuid NOT NULL UNIQUE,
+  client_id uuid UNIQUE REFERENCES public.clients(id),
+  principal_id uuid UNIQUE,
+  actor_principal_id uuid NOT NULL REFERENCES public.platform_human_principals(principal_id),
+  contract_version text NOT NULL CHECK (contract_version = 'identity.erasure.v1'),
+  contributor_versions jsonb NOT NULL,
+  dispositions jsonb NOT NULL,
+  retained_obligations jsonb NOT NULL,
+  completed_at timestamptz NOT NULL,
+  CHECK (client_id IS NOT NULL OR principal_id IS NOT NULL)
+);

package/sql/20261019200000_communications_native_operations.sql

@@ -0,0 +1,68 @@
+-- Native communications facts only. The existing outbox owns all sync claims.
+-- CREATE-only: runtime capabilities refuse unsafe effective browser/PUBLIC ACLs.
+CREATE TABLE public.communication_native_sends (
+  id uuid PRIMARY KEY DEFAULT gen_random_uuid(),
+  binding text NOT NULL CHECK (length(binding) BETWEEN 1 AND 256),
+  source_key text NOT NULL CHECK (length(source_key) BETWEEN 1 AND 256),
+  message_id text NOT NULL CHECK (length(message_id) BETWEEN 1 AND 256),
+  recipient_fingerprint text NOT NULL CHECK (length(recipient_fingerprint) = 64),
+  template_reference text NOT NULL CHECK (length(template_reference) BETWEEN 1 AND 256),
+  accepted_at timestamptz NOT NULL,
+  observed_state text CHECK (observed_state IN ('sent','delayed','delivered','bounced','complained','failed')),
+  observed_at timestamptz,
+  last_poll_at timestamptz,
+  not_found_count integer NOT NULL DEFAULT 0 CHECK (not_found_count BETWEEN 0 AND 2147483647),
+  abandoned_at timestamptz,
+  CONSTRAINT communication_native_sends_source_key UNIQUE (binding, source_key),
+  CONSTRAINT communication_native_sends_message_key UNIQUE (binding, message_id)
+);
+CREATE INDEX communication_native_sends_poll ON public.communication_native_sends (binding, last_poll_at, accepted_at, id);
+CREATE TABLE public.communication_native_observations (
+  binding text NOT NULL,
+  observation_key text NOT NULL CHECK (length(observation_key) BETWEEN 1 AND 256),
+  send_id uuid NOT NULL REFERENCES public.communication_native_sends(id),
+  kind text NOT NULL CHECK (kind IN ('sent','delayed','delivered','bounced','complained','failed')),
+  occurred_at timestamptz NOT NULL,
+  source text NOT NULL CHECK (source IN ('poll','callback')),
+  fact_fingerprint text NOT NULL CHECK (length(fact_fingerprint) = 64),
+  CONSTRAINT communication_native_observations_pkey PRIMARY KEY (binding, observation_key)
+);
+CREATE INDEX communication_native_observations_send ON public.communication_native_observations (send_id, occurred_at, observation_key);
+CREATE TABLE public.communication_native_sync_state (
+  work_id uuid PRIMARY KEY REFERENCES public.outbox_events(id),
+  binding text NOT NULL CHECK (length(binding) BETWEEN 1 AND 256),
+  provider_kind text NOT NULL CHECK (length(provider_kind) BETWEEN 1 AND 256),
+  contact_id text NOT NULL CHECK (length(contact_id) BETWEEN 1 AND 256),
+  normalized_email text NOT NULL CHECK (length(normalized_email) BETWEEN 3 AND 320),
+  purpose text NOT NULL CHECK (purpose IN ('marketing_launch_offer','marketing_newsletter')),
+  event_kind text NOT NULL CHECK (event_kind IN ('subscribe','update','unsubscribe','suppress')),
+  origin_provider_kind text,
+  origin_provider_event_id text,
+  remote_profile_id text,
+  remote_list_id text,
+  response_summary jsonb NOT NULL DEFAULT '{}' CHECK (jsonb_typeof(response_summary) = 'object'),
+  command_fingerprint text NOT NULL CHECK (length(command_fingerprint) = 64),
+  max_attempts integer NOT NULL DEFAULT 8 CHECK (max_attempts BETWEEN 1 AND 20)
+);
+CREATE TABLE public.notification_recipients (
+  id uuid PRIMARY KEY DEFAULT gen_random_uuid(),
+  email text NOT NULL CHECK (email = lower(btrim(email))),
+  name text,
+  active boolean NOT NULL DEFAULT true,
+  notification_type text NOT NULL CHECK (notification_type IN ('packaging_digest','new_signup','commerce_payment_critical')),
+  created_at timestamptz NOT NULL DEFAULT now(),
+  updated_at timestamptz NOT NULL DEFAULT now(),
+  CONSTRAINT notification_recipients_type_email_key UNIQUE (notification_type, email)
+);
+CREATE INDEX notification_recipients_order ON public.notification_recipients (notification_type, created_at, id);
+CREATE TABLE public.communication_native_policy_decisions (
+  id uuid PRIMARY KEY DEFAULT gen_random_uuid(),
+  recipient_fingerprint text NOT NULL CHECK (length(recipient_fingerprint) = 64),
+  purpose text NOT NULL CHECK (length(purpose) BETWEEN 1 AND 256),
+  allowed boolean NOT NULL,
+  reason text NOT NULL CHECK (length(reason) BETWEEN 1 AND 256),
+  permission_snapshot jsonb NOT NULL CHECK (jsonb_typeof(permission_snapshot) = 'object'),
+  source_table text,
+  source_id text,
+  evaluated_at timestamptz NOT NULL DEFAULT now()
+);

package/src/communications/accountingDocumentDelivery.ts

@@ -0,0 +1,63 @@
+import { createHash } from "node:crypto";
+
+/**
+ * The sealed transport boundary for handing an accounting document to its recipient.
+ *
+ * The kernel exercises the whole capability up to this line: a document is owed, registered with
+ * whatever authority the market has, queued, claimed and settled against a receipt. What crosses
+ * the line is one opaque hand-off, and this adapter is the deliberately inert implementation of
+ * it -- deterministic, and leaving the installation by no route at all.
+ *
+ * It is FAIL CLOSED, and that is the whole design. An installation that has declared no delivery
+ * channel gets a refusal, never a silent success: a boundary whose default answer is "fine" is
+ * how a deployment discovers months later that nothing was ever handed to anyone.
+ */
+export type CapturedDocumentDeliveryCommand = {
+  readonly deliveryId: string;
+  readonly recipientReference: string;
+};
+
+export type CapturedDocumentDeliveryPort = {
+  deliver(command: CapturedDocumentDeliveryCommand): Promise<{ readonly receiptReference: string }>;
+};
+
+export type CapturedDocumentDeliveryResolution =
+  | { readonly port: CapturedDocumentDeliveryPort; readonly refused?: undefined }
+  | { readonly port?: undefined; readonly refused: string };
+
+/** The one marker that opens the boundary. Anything else, including its absence, is a refusal. */
+export const CAPTURED_DOCUMENT_DELIVERY_CHANNEL = "captured";
+const CHANNEL_KEY = "PLATFORM_DOCUMENT_DELIVERY_CHANNEL";
+
+const reference = (command: CapturedDocumentDeliveryCommand): string =>
+  `captured:${createHash("sha256")
+    .update(`${command.deliveryId}::${command.recipientReference}`)
+    .digest("hex")
+    .slice(0, 32)}`;
+
+/**
+ * Resolve the boundary for one installation. The environment is the only input, and every path
+ * that is not an explicit declaration of the captured channel ends in a named refusal.
+ */
+export function resolveCapturedDocumentDelivery(
+  env: Record<string, string | undefined>,
+): CapturedDocumentDeliveryResolution {
+  const declared = env[CHANNEL_KEY]?.trim().toLowerCase() ?? "";
+  if (declared === "") return { refused: "document_delivery_channel_undeclared" };
+  if (declared !== CAPTURED_DOCUMENT_DELIVERY_CHANNEL) {
+    return { refused: "document_delivery_channel_unsupported" };
+  }
+  return {
+    port: {
+      async deliver(command) {
+        if (typeof command.deliveryId !== "string" || command.deliveryId.trim() === "") {
+          throw new Error("document_delivery_command_invalid");
+        }
+        if (typeof command.recipientReference !== "string" || command.recipientReference.trim() === "") {
+          throw new Error("document_delivery_recipient_missing");
+        }
+        return { receiptReference: reference(command) };
+      },
+    },
+  };
+}

package/src/communications/authEmailError.ts

@@ -0,0 +1,10 @@
+/** Typed refusal used by public/default composition when product copy is absent. */
+export class AuthEmailContentUnavailableError extends Error {
+  readonly code = "auth_email_content_unavailable";
+
+  constructor() {
+    super("Auth email content unavailable");
+    this.name = "AuthEmailContentUnavailableError";
+  }
+}
+

package/src/communications/authEmailPorts.ts

@@ -0,0 +1,2 @@
+export type * from "./contracts/authEmail.js";
+export { AuthEmailContentUnavailableError } from "./authEmailError.js";