@echovisionlab/geul-telemetry 0.1.0

package/src/audit/source-locale.ts

@@ -0,0 +1,337 @@
+import type { AuditAction, AuditRecord } from "../records.ts";
+import { assertOnlyAuditAttributes } from "./attributes.ts";
+import { buildAuditRecord } from "./builder.ts";
+import { AUDIT_CATALOG, requireCatalogTarget } from "./catalog.ts";
+import { isCanonicalAuditLocale } from "./locale-code.ts";
+import type { AuditMetadata } from "./types.ts";
+
+type SourceLocaleAction = Extract<
+  AuditAction,
+  | "post.updated"
+  | "page.updated"
+  | "work.updated"
+  | "post_series.updated"
+  | "program_event.updated"
+  | "release.updated"
+  | "artist.updated"
+  | "label.updated"
+  | "menu.updated"
+  | "campaign.updated"
+  | "form.updated"
+  | "email_template.updated"
+  | "email_layout.updated"
+  | "legal_policy.updated"
+>;
+
+const sourceLocaleActions = new Set<SourceLocaleAction>([
+  "post.updated",
+  "page.updated",
+  "work.updated",
+  "post_series.updated",
+  "program_event.updated",
+  "release.updated",
+  "artist.updated",
+  "label.updated",
+  "menu.updated",
+  "campaign.updated",
+  "form.updated",
+  "email_template.updated",
+  "email_layout.updated",
+  "legal_policy.updated",
+]);
+
+/** Recognizes exactly the reviewed source-locale variant, never a generic update. */
+export function validateSourceLocaleAuditRecord(record: AuditRecord): boolean {
+  if (
+    record.changed_fields?.length !== 1 ||
+    record.changed_fields[0] !== "source_locale"
+  )
+    return false;
+  if (!sourceLocaleActions.has(record.action as SourceLocaleAction))
+    throw new TypeError(
+      `audit action ${record.action} does not support source_locale`,
+    );
+  requireCatalogTarget(record.action, record.target_type, record.target_id);
+  if (record.actor_kind !== "member")
+    throw new TypeError("source_locale requires a member actor");
+  if (
+    !isCanonicalAuditLocale(record.previous_locale) ||
+    !isCanonicalAuditLocale(record.new_locale) ||
+    record.previous_locale === record.new_locale
+  )
+    throw new TypeError(
+      "source_locale requires distinct bounded previous_locale and new_locale",
+    );
+  const allowed = ["changed_fields", "previous_locale", "new_locale"];
+  if (record.action === "legal_policy.updated") {
+    if (
+      (record.policy_type !== "terms" && record.policy_type !== "privacy") ||
+      !Number.isSafeInteger(record.version_number) ||
+      record.version_number === undefined ||
+      record.version_number < 1
+    )
+      throw new TypeError(
+        "legal policy requires policy_type and version_number",
+      );
+    allowed.push("policy_type", "version_number");
+  }
+  assertOnlyAuditAttributes(record, allowed);
+  return true;
+}
+
+function buildSourceLocaleAuditRecord(
+  metadata: AuditMetadata,
+  action: SourceLocaleAction,
+  id: string,
+  previousLocale: string,
+  newLocale: string,
+): AuditRecord {
+  return buildAuditRecord(
+    metadata,
+    { action, target_type: AUDIT_CATALOG[action], target_id: id },
+    {
+      changed_fields: ["source_locale"],
+      previous_locale: previousLocale,
+      new_locale: newLocale,
+    },
+  );
+}
+
+export function buildPostSourceLocaleAuditRecord(
+  m: AuditMetadata,
+  id: string,
+  previousLocale: string,
+  newLocale: string,
+): AuditRecord {
+  return buildSourceLocaleAuditRecord(
+    m,
+    "post.updated",
+    id,
+    previousLocale,
+    newLocale,
+  );
+}
+export function buildPageSourceLocaleAuditRecord(
+  m: AuditMetadata,
+  id: string,
+  previousLocale: string,
+  newLocale: string,
+): AuditRecord {
+  return buildSourceLocaleAuditRecord(
+    m,
+    "page.updated",
+    id,
+    previousLocale,
+    newLocale,
+  );
+}
+export function buildWorkSourceLocaleAuditRecord(
+  m: AuditMetadata,
+  id: string,
+  previousLocale: string,
+  newLocale: string,
+): AuditRecord {
+  return buildSourceLocaleAuditRecord(
+    m,
+    "work.updated",
+    id,
+    previousLocale,
+    newLocale,
+  );
+}
+export function buildPostSeriesSourceLocaleAuditRecord(
+  m: AuditMetadata,
+  id: string,
+  previousLocale: string,
+  newLocale: string,
+): AuditRecord {
+  return buildSourceLocaleAuditRecord(
+    m,
+    "post_series.updated",
+    id,
+    previousLocale,
+    newLocale,
+  );
+}
+export function buildProgramEventSourceLocaleAuditRecord(
+  m: AuditMetadata,
+  id: string,
+  previousLocale: string,
+  newLocale: string,
+): AuditRecord {
+  return buildSourceLocaleAuditRecord(
+    m,
+    "program_event.updated",
+    id,
+    previousLocale,
+    newLocale,
+  );
+}
+export function buildReleaseSourceLocaleAuditRecord(
+  m: AuditMetadata,
+  id: string,
+  previousLocale: string,
+  newLocale: string,
+): AuditRecord {
+  return buildSourceLocaleAuditRecord(
+    m,
+    "release.updated",
+    id,
+    previousLocale,
+    newLocale,
+  );
+}
+export function buildArtistSourceLocaleAuditRecord(
+  m: AuditMetadata,
+  id: string,
+  previousLocale: string,
+  newLocale: string,
+): AuditRecord {
+  return buildSourceLocaleAuditRecord(
+    m,
+    "artist.updated",
+    id,
+    previousLocale,
+    newLocale,
+  );
+}
+export function buildLabelSourceLocaleAuditRecord(
+  m: AuditMetadata,
+  id: string,
+  previousLocale: string,
+  newLocale: string,
+): AuditRecord {
+  return buildSourceLocaleAuditRecord(
+    m,
+    "label.updated",
+    id,
+    previousLocale,
+    newLocale,
+  );
+}
+export function buildMenuSourceLocaleAuditRecord(
+  m: AuditMetadata,
+  id: string,
+  previousLocale: string,
+  newLocale: string,
+): AuditRecord {
+  return buildSourceLocaleAuditRecord(
+    m,
+    "menu.updated",
+    id,
+    previousLocale,
+    newLocale,
+  );
+}
+export function buildCampaignSourceLocaleAuditRecord(
+  m: AuditMetadata,
+  id: string,
+  previousLocale: string,
+  newLocale: string,
+): AuditRecord {
+  return buildSourceLocaleAuditRecord(
+    m,
+    "campaign.updated",
+    id,
+    previousLocale,
+    newLocale,
+  );
+}
+export function buildFormSourceLocaleAuditRecord(
+  m: AuditMetadata,
+  id: string,
+  previousLocale: string,
+  newLocale: string,
+): AuditRecord {
+  return buildSourceLocaleAuditRecord(
+    m,
+    "form.updated",
+    id,
+    previousLocale,
+    newLocale,
+  );
+}
+export function buildEmailTemplateSourceLocaleAuditRecord(
+  m: AuditMetadata,
+  id: string,
+  previousLocale: string,
+  newLocale: string,
+): AuditRecord {
+  return buildSourceLocaleAuditRecord(
+    m,
+    "email_template.updated",
+    id,
+    previousLocale,
+    newLocale,
+  );
+}
+export function buildEmailLayoutSourceLocaleAuditRecord(
+  m: AuditMetadata,
+  id: string,
+  previousLocale: string,
+  newLocale: string,
+): AuditRecord {
+  return buildSourceLocaleAuditRecord(
+    m,
+    "email_layout.updated",
+    id,
+    previousLocale,
+    newLocale,
+  );
+}
+function buildLegalPolicySourceLocaleAuditRecord(
+  metadata: AuditMetadata,
+  id: string,
+  policyType: "terms" | "privacy",
+  versionNumber: number,
+  previousLocale: string,
+  newLocale: string,
+): AuditRecord {
+  return buildAuditRecord(
+    metadata,
+    {
+      action: "legal_policy.updated",
+      target_type: AUDIT_CATALOG["legal_policy.updated"],
+      target_id: id,
+    },
+    {
+      changed_fields: ["source_locale"],
+      policy_type: policyType,
+      version_number: versionNumber,
+      previous_locale: previousLocale,
+      new_locale: newLocale,
+    },
+  );
+}
+export function buildPrivacySourceLocaleAuditRecord(
+  m: AuditMetadata,
+  id: string,
+  versionNumber: number,
+  previousLocale: string,
+  newLocale: string,
+): AuditRecord {
+  return buildLegalPolicySourceLocaleAuditRecord(
+    m,
+    id,
+    "privacy",
+    versionNumber,
+    previousLocale,
+    newLocale,
+  );
+}
+export function buildTermsSourceLocaleAuditRecord(
+  m: AuditMetadata,
+  id: string,
+  versionNumber: number,
+  previousLocale: string,
+  newLocale: string,
+): AuditRecord {
+  return buildLegalPolicySourceLocaleAuditRecord(
+    m,
+    id,
+    "terms",
+    versionNumber,
+    previousLocale,
+    newLocale,
+  );
+}

package/src/audit/types.ts

@@ -0,0 +1,9 @@
+import type { RecordActor } from "../actor.ts";
+import type { Correlation } from "../records.ts";
+
+/** Metadata shared by every domain-audit record. */
+export type AuditMetadata = Correlation &
+  RecordActor & {
+    readonly audit_id: string;
+    readonly occurred_at: string;
+  };

package/src/audit.ts

@@ -0,0 +1,21 @@
+// Public compatibility facade. Domain modules remain internal implementation
+// boundaries; package consumers import the supported root export.
+export * from "./audit/account.ts";
+export * from "./audit/attributes.ts";
+export * from "./audit/artist-label.ts";
+export * from "./audit/content.ts";
+export * from "./audit/email-authoring.ts";
+export * from "./audit/file.ts";
+export * from "./audit/form.ts";
+export * from "./audit/integrations.ts";
+export * from "./audit/member.ts";
+export * from "./audit/program.ts";
+export * from "./audit/reference-data.ts";
+export * from "./audit/reference-entities.ts";
+export * from "./audit/relation-download-policy.ts";
+export * from "./audit/release-campaign.ts";
+export * from "./audit/settings.ts";
+export * from "./audit/series-type.ts";
+export * from "./audit/source-locale.ts";
+export * from "./audit/locale-content.ts";
+export * from "./audit/types.ts";

package/src/authentication.ts

@@ -0,0 +1,183 @@
+import type { RecordActor } from "./actor.ts";
+import {
+  validateSecurityAccessRecord,
+  type AuthenticationBlockReason,
+  type AuthenticationFailureReason,
+  type AuthenticationFlowKind,
+  type AuthenticationMethod,
+  type AuthenticationPrincipalState,
+  type AuthorizationDenialReason,
+  type Correlation,
+  type SecurityAccessRecord,
+} from "./records.ts";
+
+export type SecurityAccessMetadata = Correlation &
+  RecordActor & {
+    readonly access_id: string;
+    readonly occurred_at: string;
+    readonly source_ip: string;
+  };
+
+export interface AuthenticationContext {
+  readonly flow_kind?: AuthenticationFlowKind;
+  readonly authentication_method?: AuthenticationMethod;
+  readonly principal_state?: AuthenticationPrincipalState;
+  readonly provider?: string;
+}
+
+export function buildAuthenticationSucceededRecord(
+  metadata: SecurityAccessMetadata,
+  authentication: Required<
+    Pick<
+      AuthenticationContext,
+      "flow_kind" | "authentication_method" | "principal_state"
+    >
+  > &
+    Pick<AuthenticationContext, "provider">,
+): SecurityAccessRecord {
+  return buildSecurityAccessRecord(metadata, {
+    action: "authentication.succeeded",
+    ...authentication,
+  });
+}
+
+export function buildAuthenticationFailedRecord(
+  metadata: SecurityAccessMetadata,
+  authentication: Required<
+    Pick<AuthenticationContext, "flow_kind" | "authentication_method">
+  > &
+    Pick<AuthenticationContext, "provider">,
+  reason: AuthenticationFailureReason,
+): SecurityAccessRecord {
+  return buildSecurityAccessRecord(metadata, {
+    action: "authentication.failed",
+    ...authentication,
+    reason,
+  });
+}
+
+export function buildAuthenticationBlockedRecord(
+  metadata: SecurityAccessMetadata,
+  authentication: AuthenticationContext,
+  reason: AuthenticationBlockReason,
+): SecurityAccessRecord {
+  return buildSecurityAccessRecord(metadata, {
+    action: "authentication.blocked",
+    ...authentication,
+    reason,
+  });
+}
+
+export function buildAuthorizationDeniedRecord(
+  metadata: SecurityAccessMetadata,
+  procedure: string,
+  reason: AuthorizationDenialReason,
+): SecurityAccessRecord {
+  return buildSecurityAccessRecord(metadata, {
+    action: "authorization.denied",
+    attempted_action: procedure,
+    permission: "procedure:invoke",
+    reason,
+  });
+}
+
+export function buildMemberCollectionAccessedRecord(
+  metadata: SecurityAccessMetadata,
+): SecurityAccessRecord {
+  return buildPersonalDataAccessedRecord(
+    metadata,
+    "member_collection",
+    "1",
+    "member_administration",
+  );
+}
+
+export function buildMemberAccessedRecord(
+  metadata: SecurityAccessMetadata,
+  memberId: string,
+): SecurityAccessRecord {
+  return buildPersonalDataAccessedRecord(
+    metadata,
+    "member",
+    memberId,
+    "member_administration",
+  );
+}
+
+export function buildCampaignRecipientsAccessedRecord(
+  metadata: SecurityAccessMetadata,
+  campaignId: string,
+): SecurityAccessRecord {
+  return buildPersonalDataAccessedRecord(
+    metadata,
+    "campaign",
+    campaignId,
+    "campaign_recipients",
+  );
+}
+
+export function buildFormSubmissionsAccessedRecord(
+  metadata: SecurityAccessMetadata,
+  formId: string,
+): SecurityAccessRecord {
+  return buildPersonalDataAccessedRecord(
+    metadata,
+    "form",
+    formId,
+    "form_submissions",
+  );
+}
+
+export function buildFormSubmissionAccessedRecord(
+  metadata: SecurityAccessMetadata,
+  submissionId: string,
+): SecurityAccessRecord {
+  return buildPersonalDataAccessedRecord(
+    metadata,
+    "form_submission",
+    submissionId,
+    "form_submission",
+  );
+}
+
+function buildPersonalDataAccessedRecord(
+  metadata: SecurityAccessMetadata,
+  subjectType: string,
+  subjectId: string,
+  dataCategory: string,
+): SecurityAccessRecord {
+  return buildSecurityAccessRecord(metadata, {
+    action: "personal_data.accessed",
+    subject_type: subjectType,
+    subject_id: subjectId,
+    access_kind: "read",
+    data_category: dataCategory,
+  });
+}
+
+export function authenticationMethodFromKratos(
+  value: string,
+): AuthenticationMethod {
+  switch (value) {
+    case "code":
+      return "email_code";
+    case "oidc":
+      return "oidc";
+    case "passkey":
+      return "passkey";
+    default:
+      throw new TypeError("unsupported authentication method");
+  }
+}
+
+function buildSecurityAccessRecord(
+  metadata: SecurityAccessMetadata,
+  attributes: Omit<
+    SecurityAccessRecord,
+    keyof SecurityAccessMetadata | keyof Correlation | keyof RecordActor
+  >,
+): SecurityAccessRecord {
+  const record = { ...metadata, ...attributes } as SecurityAccessRecord;
+  validateSecurityAccessRecord(record);
+  return record;
+}

package/src/error-metadata.ts

@@ -0,0 +1,11 @@
+import { normalizeKey } from "./log-attribute-policy.ts";
+
+export function stableErrorType(value: unknown): string {
+  if (value instanceof Error) {
+    const errorName = normalizeKey(value.name);
+    if (errorName !== "" && errorName !== "error") return errorName;
+    const constructorName = normalizeKey(value.constructor.name);
+    if (constructorName !== "") return constructorName;
+  }
+  return "reported_error";
+}

package/src/index.ts

@@ -0,0 +1,11 @@
+export * from "./actor.ts";
+export * from "./audit.ts";
+export * from "./authentication.ts";
+export * from "./job.ts";
+export * from "./otel.ts";
+export * from "./records.ts";
+export * from "./redaction.ts";
+export * from "./request.ts";
+export * from "./request-context.ts";
+export * from "./system.ts";
+export * from "./trace.ts";

package/src/job.ts

@@ -0,0 +1,56 @@
+export const JOB_KIND_MESH_OPTIMIZATION = "mesh_optimization";
+export const JOB_KIND_OG_GENERATION = "og_generation";
+
+export const CANONICAL_JOB_KINDS = [
+  JOB_KIND_MESH_OPTIMIZATION,
+  JOB_KIND_OG_GENERATION,
+] as const;
+
+export type JobKind = (typeof CANONICAL_JOB_KINDS)[number];
+
+export const JOB_FAILURE_REASONS = {
+  [JOB_KIND_MESH_OPTIMIZATION]: [
+    "rejected",
+    "source_not_found",
+    "download_failed",
+    "optimization_failed",
+    "upload_failed",
+    "internal",
+  ],
+  [JOB_KIND_OG_GENERATION]: [
+    "invalid_claim",
+    "source_rejected",
+    "processing_failed",
+    "integrity_failed",
+    "completion_rejected",
+  ],
+} as const satisfies Record<JobKind, readonly string[]>;
+
+export type JobFailureReason = (typeof JOB_FAILURE_REASONS)[JobKind][number];
+
+const canonicalJobKinds = new Set<string>(CANONICAL_JOB_KINDS);
+
+export function parseJobKind(value: string): JobKind {
+  if (!canonicalJobKinds.has(value)) {
+    throw new TypeError(`unknown canonical job kind ${JSON.stringify(value)}`);
+  }
+  return value as JobKind;
+}
+
+export function parseJobFailureReason(
+  jobKind: JobKind,
+  value: string,
+): JobFailureReason {
+  const reasons = JOB_FAILURE_REASONS[jobKind] as readonly string[] | undefined;
+  if (reasons === undefined) {
+    throw new TypeError(
+      `unknown canonical job kind ${JSON.stringify(jobKind)}`,
+    );
+  }
+  if (!reasons.includes(value)) {
+    throw new TypeError(
+      `unknown failure reason ${JSON.stringify(value)} for job kind ${JSON.stringify(jobKind)}`,
+    );
+  }
+  return value as JobFailureReason;
+}

package/src/log-attribute-policy.ts

@@ -0,0 +1,21 @@
+import policy from "../policy/log-redaction.json" with { type: "json" };
+
+const forbiddenKeys = new Set<string>(policy.exact);
+
+export function normalizeKey(key: string): string {
+  return key
+    .trim()
+    .replace(/([a-z\d])([A-Z])/g, "$1_$2")
+    .replace(/[^\p{L}\p{N}]+/gu, "_")
+    .replace(/^_+|_+$/g, "")
+    .toLowerCase();
+}
+
+export function isForbiddenKey(key: string): boolean {
+  const normalized = normalizeKey(key);
+  return (
+    forbiddenKeys.has(normalized) ||
+    policy.suffixes.some((suffix) => normalized.endsWith(suffix)) ||
+    policy.prefixes.some((prefix) => normalized.startsWith(prefix))
+  );
+}