@echovisionlab/geul-telemetry 0.1.0

package/src/audit/account.ts

@@ -0,0 +1,206 @@
+import type {
+  AccountSessionScope,
+  AuditCollectionOperation,
+  AuditRecord,
+  AuditState,
+} from "../records.ts";
+import { canonicalAuditValues } from "./attributes.ts";
+import { buildAuditRecord } from "./builder.ts";
+import type { AuditMetadata } from "./types.ts";
+
+function updated(
+  metadata: AuditMetadata,
+  memberId: string,
+  attributes: Parameters<typeof buildAuditRecord>[2],
+): AuditRecord {
+  return buildAuditRecord(
+    metadata,
+    {
+      action: "account.updated",
+      target_type: "account",
+      target_id: memberId,
+    },
+    attributes,
+  );
+}
+export function buildAccountCanonicalEmailUpdatedAuditRecord(
+  metadata: AuditMetadata,
+  memberId: string,
+  previousEmail: string,
+  newEmail: string,
+): AuditRecord {
+  return updated(metadata, memberId, {
+    changed_fields: ["canonical_email"],
+    previous_email: previousEmail,
+    new_email: newEmail,
+  });
+}
+function login(
+  metadata: AuditMetadata,
+  memberId: string,
+  operation: AuditCollectionOperation,
+  email: string,
+): AuditRecord {
+  return updated(metadata, memberId, {
+    changed_fields: ["login_emails"],
+    collection_operation: operation,
+    email,
+  });
+}
+export function buildAccountEmailLoginAddedAuditRecord(
+  metadata: AuditMetadata,
+  memberId: string,
+  email: string,
+): AuditRecord {
+  return login(metadata, memberId, "added", email);
+}
+export function buildAccountEmailLoginRemovedAuditRecord(
+  metadata: AuditMetadata,
+  memberId: string,
+  email: string,
+): AuditRecord {
+  return login(metadata, memberId, "removed", email);
+}
+function social(
+  metadata: AuditMetadata,
+  memberId: string,
+  operation: AuditCollectionOperation,
+  provider: string,
+  providerSubject: string,
+): AuditRecord {
+  return updated(metadata, memberId, {
+    changed_fields: ["social_logins"],
+    collection_operation: operation,
+    provider,
+    provider_subject: providerSubject,
+  });
+}
+export function buildAccountSocialLoginAddedAuditRecord(
+  metadata: AuditMetadata,
+  memberId: string,
+  provider: string,
+  providerSubject: string,
+): AuditRecord {
+  return social(metadata, memberId, "added", provider, providerSubject);
+}
+export function buildAccountSocialLoginRemovedAuditRecord(
+  metadata: AuditMetadata,
+  memberId: string,
+  provider: string,
+  providerSubject: string,
+): AuditRecord {
+  return social(metadata, memberId, "removed", provider, providerSubject);
+}
+function passkeys(
+  metadata: AuditMetadata,
+  memberId: string,
+  operation: AuditCollectionOperation,
+  passkeyIds: readonly string[],
+): AuditRecord {
+  return updated(metadata, memberId, {
+    changed_fields: ["passkeys"],
+    collection_operation: operation,
+    passkey_ids: canonicalAuditValues(passkeyIds),
+  });
+}
+export function buildAccountPasskeyAddedAuditRecord(
+  metadata: AuditMetadata,
+  memberId: string,
+  passkeyIds: readonly string[],
+): AuditRecord {
+  return passkeys(metadata, memberId, "added", passkeyIds);
+}
+export function buildAccountPasskeyRemovedAuditRecord(
+  metadata: AuditMetadata,
+  memberId: string,
+  passkeyIds: readonly string[],
+): AuditRecord {
+  return passkeys(metadata, memberId, "removed", passkeyIds);
+}
+export function buildAccountSessionRevokedAuditRecord(
+  metadata: AuditMetadata,
+  memberId: string,
+  sessionScope: AccountSessionScope,
+  sessionIds: readonly string[],
+): AuditRecord {
+  return updated(metadata, memberId, {
+    changed_fields: ["sessions"],
+    collection_operation: "removed",
+    session_scope: sessionScope,
+    session_ids: canonicalAuditValues(sessionIds),
+  });
+}
+export function buildAccountNewsletterSubscriptionUpdatedAuditRecord(
+  metadata: AuditMetadata,
+  memberId: string,
+  previousState: AuditState,
+  newState: AuditState,
+): AuditRecord {
+  return updated(metadata, memberId, {
+    changed_fields: ["newsletter_subscription"],
+    previous_state: previousState,
+    new_state: newState,
+  });
+}
+function deletionState(
+  metadata: AuditMetadata,
+  memberId: string,
+  previousState: AuditState,
+  newState: AuditState,
+): AuditRecord {
+  return updated(metadata, memberId, {
+    changed_fields: ["deletion_state"],
+    previous_state: previousState,
+    new_state: newState,
+  });
+}
+export function buildAccountDeletionRequestedAuditRecord(
+  metadata: AuditMetadata,
+  memberId: string,
+  previousState: AuditState,
+): AuditRecord {
+  return deletionState(
+    metadata,
+    memberId,
+    previousState,
+    "confirmation_pending",
+  );
+}
+export function buildAccountDeletionScheduledAuditRecord(
+  metadata: AuditMetadata,
+  memberId: string,
+  previousState: AuditState,
+): AuditRecord {
+  return deletionState(metadata, memberId, previousState, "scheduled");
+}
+export function buildAccountDeletionCancelledAuditRecord(
+  metadata: AuditMetadata,
+  memberId: string,
+): AuditRecord {
+  return deletionState(metadata, memberId, "scheduled", "cancelled");
+}
+export function buildAccountDeletionRecoveredAuditRecord(
+  metadata: AuditMetadata,
+  memberId: string,
+): AuditRecord {
+  return deletionState(
+    metadata,
+    memberId,
+    "recovery_confirmation_pending",
+    "recovered",
+  );
+}
+export function buildAccountDeletedAuditRecord(
+  metadata: AuditMetadata,
+  memberId: string,
+): AuditRecord {
+  return buildAuditRecord(
+    metadata,
+    {
+      action: "account.deleted",
+      target_type: "account",
+      target_id: memberId,
+    },
+    {},
+  );
+}

package/src/audit/actor-policy.ts

@@ -0,0 +1,63 @@
+import type { AuditRecord } from "../records.ts";
+
+const SYSTEM_AUDIT_SERVICES: Readonly<Record<string, readonly string[]>> = {
+  "account.deleted": ["geul-backend"],
+  "file.deleted": ["geul-backend"],
+  "post.updated": ["geul-collab"],
+  "page.updated": ["geul-collab"],
+  "work.updated": ["geul-collab"],
+  "release.updated": ["geul-collab"],
+  "campaign.updated": ["geul-backend"],
+  "legal_policy.updated": ["geul-backend"],
+  "member.updated": ["geul-backend"],
+};
+
+const ANONYMOUS_AUDIT_ACTIONS = new Set(["form_submission.created"]);
+
+export function auditActionAllowsAnonymous(action: string): boolean {
+  return ANONYMOUS_AUDIT_ACTIONS.has(action);
+}
+
+/** Explicit catalog policy for the few mutations a system actor may append. */
+export function systemActorMayAppendAudit(record: AuditRecord): boolean {
+  if (
+    !SYSTEM_AUDIT_SERVICES[record.action]?.includes(
+      String(record.actor_service),
+    )
+  )
+    return false;
+  if (record.action === "release.updated")
+    return (
+      record.actor_service === "geul-collab" &&
+      record.changed_fields?.length === 1 &&
+      ["track_audio"].includes(record.changed_fields[0] ?? "")
+    );
+  if (record.action === "campaign.updated") {
+    return (
+      record.actor_service === "geul-backend" &&
+      record.changed_fields?.length === 1 &&
+      record.changed_fields[0] === "status" &&
+      (record.new_state === "sent" || record.new_state === "failed")
+    );
+  }
+  if (
+    record.action === "post.updated" ||
+    record.action === "page.updated" ||
+    record.action === "work.updated"
+  ) {
+    return (
+      record.actor_service === "geul-collab" &&
+      record.changed_fields?.length === 1 &&
+      record.changed_fields[0] === "version"
+    );
+  }
+  if (record.action !== "member.updated") return true;
+  return (
+    (record.changed_fields?.length === 1 &&
+      record.changed_fields[0] === "role") ||
+    (record.changed_fields?.length === 1 &&
+      record.changed_fields[0] === "status" &&
+      record.previous_state === "banned" &&
+      record.new_state === "active")
+  );
+}

package/src/audit/artist-label.ts

@@ -0,0 +1,312 @@
+import type {
+  AuditAssetSlot,
+  AuditCollectionOperation,
+  AuditRecord,
+  AuditRelationship,
+  AuditState,
+} from "../records.ts";
+import { assertOnlyAuditAttributes } from "./attributes.ts";
+import { buildAuditRecord } from "./builder.ts";
+import {
+  AUDIT_ACTIONS,
+  AUDIT_CATALOG,
+  requireCatalogTarget,
+} from "./catalog.ts";
+import type { AuditMetadata } from "./types.ts";
+
+type ArtistLabelTarget = "artist" | "label";
+type ArtistLabelAction = Extract<
+  (typeof AUDIT_ACTIONS)[number],
+  | "artist.created"
+  | "artist.updated"
+  | "artist.deleted"
+  | "label.created"
+  | "label.updated"
+  | "label.deleted"
+>;
+type ArtistLabelLifecycleState = Extract<AuditState, "draft" | "published">;
+type ShareLinkOperation = "created" | "deleted";
+
+const targetTypes = new Set<ArtistLabelTarget>(["artist", "label"]);
+const artistLabelActions = new Set<ArtistLabelAction>(
+  AUDIT_ACTIONS.filter((action) =>
+    targetTypes.has(AUDIT_CATALOG[action] as ArtistLabelTarget),
+  ) as ArtistLabelAction[],
+);
+function buildArtistLabelAuditRecord(
+  metadata: AuditMetadata,
+  action: ArtistLabelAction,
+  targetId: string,
+  attributes: Parameters<typeof buildAuditRecord>[2] = {},
+): AuditRecord {
+  return buildAuditRecord(
+    metadata,
+    { action, target_type: AUDIT_CATALOG[action], target_id: targetId },
+    attributes,
+  );
+}
+function requireNoExtra(record: AuditRecord, allowed: readonly string[]): void {
+  assertOnlyAuditAttributes(record, allowed);
+}
+function requireIdentifier(name: string, value: string | undefined): void {
+  if (!value || value.length > 255 || value.trim() !== value)
+    throw new TypeError(`${name} requires an identifier`);
+}
+function requireMemberActor(record: AuditRecord): void {
+  if (record.actor_kind !== "member")
+    throw new TypeError(
+      "artist and label mutation variants require member actor",
+    );
+}
+function requireLifecycle(record: AuditRecord): void {
+  if (
+    record.changed_fields?.length !== 1 ||
+    record.changed_fields[0] !== "status" ||
+    !(
+      (record.previous_state === "draft" && record.new_state === "published") ||
+      (record.previous_state === "published" && record.new_state === "draft")
+    )
+  )
+    throw new TypeError("lifecycle requires draft/published transition");
+  requireNoExtra(record, ["changed_fields", "previous_state", "new_state"]);
+}
+function requireParticipant(record: AuditRecord): void {
+  if (
+    record.changed_fields?.length !== 1 ||
+    record.changed_fields[0] !== "participants" ||
+    !["none", "owner", "manager"].includes(
+      record.previous_relationship ?? "",
+    ) ||
+    !["none", "owner", "manager"].includes(record.new_relationship ?? "") ||
+    record.previous_relationship === record.new_relationship
+  )
+    throw new TypeError(
+      "participant requires an allowed relationship transition",
+    );
+  requireIdentifier("subject_member_id", record.subject_member_id);
+  requireNoExtra(record, [
+    "changed_fields",
+    "subject_member_id",
+    "previous_relationship",
+    "new_relationship",
+  ]);
+}
+function requireShareLink(record: AuditRecord): void {
+  if (
+    record.changed_fields?.length !== 1 ||
+    record.changed_fields[0] !== "share_links" ||
+    (record.item_operation !== "created" && record.item_operation !== "deleted")
+  )
+    throw new TypeError(
+      "share link requires created or deleted item operation",
+    );
+  requireIdentifier("item_id", record.item_id);
+  requireNoExtra(record, ["changed_fields", "item_operation", "item_id"]);
+}
+function requireGallery(record: AuditRecord): void {
+  if (
+    record.changed_fields?.length !== 1 ||
+    record.changed_fields[0] !== "gallery" ||
+    record.file_ids === undefined
+  )
+    throw new TypeError("artist gallery requires file_ids");
+  const seen = new Set<string>();
+  for (const fileId of record.file_ids) {
+    requireIdentifier("file_ids", fileId);
+    if (seen.has(fileId))
+      throw new TypeError("artist gallery requires unique file_ids");
+    seen.add(fileId);
+  }
+  requireNoExtra(record, ["changed_fields", "file_ids"]);
+}
+function requireLogo(record: AuditRecord): void {
+  if (
+    record.changed_fields?.length !== 1 ||
+    record.changed_fields[0] !== "logo" ||
+    (record.asset_slot !== "light" && record.asset_slot !== "dark") ||
+    (record.collection_operation !== "added" &&
+      record.collection_operation !== "removed")
+  )
+    throw new TypeError("label logo requires slot and operation");
+  requireIdentifier("asset_id", record.asset_id);
+  requireNoExtra(record, [
+    "changed_fields",
+    "asset_slot",
+    "collection_operation",
+    "asset_id",
+  ]);
+}
+function validateArtistUpdate(record: AuditRecord): void {
+  switch (record.changed_fields?.[0]) {
+    case "status":
+      requireMemberActor(record);
+      return requireLifecycle(record);
+    case "gallery":
+      requireMemberActor(record);
+      return requireGallery(record);
+    case "participants":
+      requireMemberActor(record);
+      return requireParticipant(record);
+    case "share_links":
+      requireMemberActor(record);
+      return requireShareLink(record);
+    default:
+      throw new TypeError("artist update rejects variant");
+  }
+}
+function validateLabelUpdate(record: AuditRecord): void {
+  switch (record.changed_fields?.[0]) {
+    case "status":
+      requireMemberActor(record);
+      return requireLifecycle(record);
+    case "participants":
+      requireMemberActor(record);
+      return requireParticipant(record);
+    case "logo":
+      requireMemberActor(record);
+      return requireLogo(record);
+    case "share_links":
+      requireMemberActor(record);
+      return requireShareLink(record);
+    default:
+      throw new TypeError("label update rejects variant");
+  }
+}
+
+/** Returns true only for reviewed Artist and Label catalog actions. */
+export function validateArtistLabelAuditRecord(record: AuditRecord): boolean {
+  if (!artistLabelActions.has(record.action as ArtistLabelAction)) return false;
+  requireCatalogTarget(record.action, record.target_type, record.target_id);
+  if (!record.action.endsWith(".updated")) {
+    requireNoExtra(record, []);
+    return true;
+  }
+  if (record.action === "artist.updated") validateArtistUpdate(record);
+  else validateLabelUpdate(record);
+  return true;
+}
+
+export function buildArtistCreatedAuditRecord(
+  metadata: AuditMetadata,
+  id: string,
+): AuditRecord {
+  return buildArtistLabelAuditRecord(metadata, "artist.created", id);
+}
+export function buildArtistDeletedAuditRecord(
+  metadata: AuditMetadata,
+  id: string,
+): AuditRecord {
+  return buildArtistLabelAuditRecord(metadata, "artist.deleted", id);
+}
+export function buildArtistLifecycleAuditRecord(
+  metadata: AuditMetadata,
+  id: string,
+  previousState: ArtistLabelLifecycleState,
+  newState: ArtistLabelLifecycleState,
+): AuditRecord {
+  return buildArtistLabelAuditRecord(metadata, "artist.updated", id, {
+    changed_fields: ["status"],
+    previous_state: previousState,
+    new_state: newState,
+  });
+}
+export function buildArtistGalleryAuditRecord(
+  metadata: AuditMetadata,
+  id: string,
+  fileIds: readonly string[],
+): AuditRecord {
+  return buildArtistLabelAuditRecord(metadata, "artist.updated", id, {
+    changed_fields: ["gallery"],
+    file_ids: [...fileIds],
+  });
+}
+export function buildArtistParticipantAuditRecord(
+  metadata: AuditMetadata,
+  id: string,
+  subjectMemberId: string,
+  previousRelationship: AuditRelationship,
+  newRelationship: AuditRelationship,
+): AuditRecord {
+  return buildArtistLabelAuditRecord(metadata, "artist.updated", id, {
+    changed_fields: ["participants"],
+    subject_member_id: subjectMemberId,
+    previous_relationship: previousRelationship,
+    new_relationship: newRelationship,
+  });
+}
+export function buildArtistShareLinkAuditRecord(
+  metadata: AuditMetadata,
+  id: string,
+  itemId: string,
+  itemOperation: ShareLinkOperation,
+): AuditRecord {
+  return buildArtistLabelAuditRecord(metadata, "artist.updated", id, {
+    changed_fields: ["share_links"],
+    item_id: itemId,
+    item_operation: itemOperation,
+  });
+}
+export function buildLabelCreatedAuditRecord(
+  metadata: AuditMetadata,
+  id: string,
+): AuditRecord {
+  return buildArtistLabelAuditRecord(metadata, "label.created", id);
+}
+export function buildLabelDeletedAuditRecord(
+  metadata: AuditMetadata,
+  id: string,
+): AuditRecord {
+  return buildArtistLabelAuditRecord(metadata, "label.deleted", id);
+}
+export function buildLabelLifecycleAuditRecord(
+  metadata: AuditMetadata,
+  id: string,
+  previousState: ArtistLabelLifecycleState,
+  newState: ArtistLabelLifecycleState,
+): AuditRecord {
+  return buildArtistLabelAuditRecord(metadata, "label.updated", id, {
+    changed_fields: ["status"],
+    previous_state: previousState,
+    new_state: newState,
+  });
+}
+export function buildLabelParticipantAuditRecord(
+  metadata: AuditMetadata,
+  id: string,
+  subjectMemberId: string,
+  previousRelationship: AuditRelationship,
+  newRelationship: AuditRelationship,
+): AuditRecord {
+  return buildArtistLabelAuditRecord(metadata, "label.updated", id, {
+    changed_fields: ["participants"],
+    subject_member_id: subjectMemberId,
+    previous_relationship: previousRelationship,
+    new_relationship: newRelationship,
+  });
+}
+export function buildLabelLogoAuditRecord(
+  metadata: AuditMetadata,
+  id: string,
+  assetSlot: AuditAssetSlot,
+  collectionOperation: AuditCollectionOperation,
+  assetId: string,
+): AuditRecord {
+  return buildArtistLabelAuditRecord(metadata, "label.updated", id, {
+    changed_fields: ["logo"],
+    asset_slot: assetSlot,
+    collection_operation: collectionOperation,
+    asset_id: assetId,
+  });
+}
+export function buildLabelShareLinkAuditRecord(
+  metadata: AuditMetadata,
+  id: string,
+  itemId: string,
+  itemOperation: ShareLinkOperation,
+): AuditRecord {
+  return buildArtistLabelAuditRecord(metadata, "label.updated", id, {
+    changed_fields: ["share_links"],
+    item_id: itemId,
+    item_operation: itemOperation,
+  });
+}

package/src/audit/attributes.ts

@@ -0,0 +1,107 @@
+import type { AuditRecord } from "../records.ts";
+
+/**
+ * Canonical wire representation for set-shaped audit attributes.  In
+ * particular, an empty input stays an explicit empty array rather than being
+ * omitted; validators decide whether a given catalog variant permits it.
+ */
+export function canonicalAuditValues(
+  values: readonly string[],
+): readonly string[] {
+  return [...new Set(values)].sort();
+}
+
+/** The complete, reviewed Domain Audit JSONB attribute namespace. */
+export const AUDIT_RECORD_ATTRIBUTE_NAMES = [
+  "nickname",
+  "asset_id",
+  "consent_id",
+  "changed_fields",
+  "collection_operation",
+  "asset_slot",
+  "previous_state",
+  "new_state",
+  "scheduled_at",
+  "scheduled_time_zone",
+  "version_id",
+  "version_number",
+  "contributor_member_ids",
+  "event_name",
+  "file_id",
+  "file_ids",
+  "item_id",
+  "item_ids",
+  "item_operation",
+  "item_scope",
+  "parent_id",
+  "policy_type",
+  "effective_at",
+  "post_ids",
+  "preferred_locale",
+  "locale",
+  "previous_locale",
+  "new_locale",
+  "previous_item_id",
+  "previous_item_ids",
+  "previous_parent_id",
+  "new_parent_id",
+  "previous_relationship",
+  "new_relationship",
+  "previous_series_id",
+  "new_series_id",
+  "subject_member_id",
+  "subject_post_id",
+  "tag_ids",
+  "tag_name",
+  "previous_role",
+  "new_role",
+  "email",
+  "previous_email",
+  "new_email",
+  "provider",
+  "provider_subject",
+  "passkey_ids",
+  "session_scope",
+  "session_ids",
+] as const;
+
+export type AuditRecordAttributeName =
+  (typeof AUDIT_RECORD_ATTRIBUTE_NAMES)[number];
+
+const auditRecordKeys = new Set<string>([
+  "audit_id",
+  "occurred_at",
+  "action",
+  "target_type",
+  "target_id",
+  "request_id",
+  "trace_id",
+  "span_id",
+  "actor_kind",
+  "actor_member_id",
+  "actor_service",
+  ...AUDIT_RECORD_ATTRIBUTE_NAMES,
+]);
+
+/** Rejects input that cannot be represented by the public Audit wire type. */
+export function assertKnownAuditRecordKeys(record: AuditRecord): void {
+  for (const key of Object.keys(record)) {
+    if (!auditRecordKeys.has(key)) {
+      throw new TypeError(`audit record has unknown attribute ${key}`);
+    }
+  }
+}
+
+/** Enforces an action variant's exact permitted attribute shape. */
+export function assertOnlyAuditAttributes(
+  record: AuditRecord,
+  allowed: readonly string[],
+): void {
+  for (const name of AUDIT_RECORD_ATTRIBUTE_NAMES) {
+    if (record[name] !== undefined && !allowed.includes(name)) {
+      throw new TypeError(
+        `audit action ${record.action} does not allow ${name}`,
+      );
+    }
+  }
+}

package/src/audit/builder.ts

@@ -0,0 +1,25 @@
+import { validateAuditRecord, type AuditRecord } from "../records.ts";
+import type { AuditMetadata } from "./types.ts";
+
+type AuditTarget = Pick<AuditRecord, "action" | "target_type" | "target_id">;
+
+// A semantic builder may supply only reviewed domain attributes. Metadata and
+// correlation are exclusively supplied by its caller, while action/target are
+// exclusively supplied by the focused domain helper.
+type AuditRecordAttributes = Omit<
+  AuditRecord,
+  keyof AuditMetadata | keyof AuditTarget
+>;
+
+/** Builds only a fully validated, catalogued audit wire record. */
+// Internal assembly point used only by focused semantic builder modules.
+// It is intentionally not re-exported from the package facade.
+export function buildAuditRecord(
+  metadata: AuditMetadata,
+  target: AuditTarget,
+  attributes: AuditRecordAttributes,
+): AuditRecord {
+  const record = { ...attributes, ...metadata, ...target } as AuditRecord;
+  validateAuditRecord(record);
+  return record;
+}