@empire-builder-kit/nx 1.0.0-rc.4 → 1.0.0-rc.40

package/src/generators/slice/built-in-plan-authorization-storage.js

@@ -0,0 +1,119 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.renderAuthorizationRecordStore = renderAuthorizationRecordStore;
+exports.renderDynamoAuthorizationStore = renderDynamoAuthorizationStore;
+/** Storage mechanics stay generated; policy, features and delegation decisions stay seeded. */
+function renderAuthorizationRecordStore() {
+    const common = `import type { AuthorizationAuditRecord } from '@empire-builder-kit/runtime/authorization';
+
+export interface AuthorizationRecord {
+  id: string;
+  ownerId: string;
+  name: string;
+  runScope: string;
+}
+export type SafeAuthorizationAudit = Omit<AuthorizationAuditRecord, 'reasonCategory'> & { reasonCategory: string };
+export type AuthorizationAuditWorkload = 'api-database-records' | 'data-export-cleanup' | 'data-retention-job' | 'event-consumer';
+`;
+    return (common +
+        `
+import { randomUUID } from 'node:crypto';
+import { dataStore } from '../data/key-value.js';
+import type { ApprovalRequest } from '@empire-builder-kit/runtime/authorization';
+
+export async function readAuthorizationRecord(_correlationId: string, id: string, ownerId?: string): Promise<AuthorizationRecord | undefined> {
+  const item = await dataStore().get('application', 'records', id);
+  if (!item) return undefined;
+  const value = item.value as Partial<AuthorizationRecord> | null;
+  if (!value || value.id !== id || typeof value.ownerId !== 'string' || typeof value.name !== 'string' || typeof value.runScope !== 'string')
+    throw new Error('Stored record identity is invalid.');
+  if (ownerId !== undefined && value.ownerId !== ownerId) return undefined;
+  return value as AuthorizationRecord;
+}
+
+/** A deleted record's owner can only be recovered from its exact durable workflow. */
+export async function readRecordDeletionApproval(id: string, recordId: string, action: string): Promise<ApprovalRequest | undefined> {
+  const row = await dataStore().get('application', 'record-deletions', id);
+  if (!row) return undefined;
+  const value = row.value as { kind?: string; schemaVersion?: number; approval?: ApprovalRequest } | null;
+  const approval = value?.approval;
+  if (value?.kind !== 'record-deletion' || value.schemaVersion !== 1 || !approval ||
+      approval.id !== id || approval.schemaVersion !== 1 || approval.action !== action ||
+      action !== approval.slice + ':record-delete' || approval.resource?.id !== recordId ||
+      approval.resource.type !== 'record' || approval.author?.authorityMode !== 'direct' ||
+      approval.author.subjectType !== 'user' || !approval.author.actorId ||
+      approval.author.effectiveHumanId !== approval.author.actorId)
+    throw new Error('Stored deletion authority is invalid.');
+  return approval;
+}
+
+export async function writeAuthorizationAudit(audit: SafeAuthorizationAudit, _workload: AuthorizationAuditWorkload): Promise<void> {
+  void _workload; // Runtime IAM owns workload scope; it is not an audit payload field.
+  // Copy only the safe projection, never caller claims, roles, secrets or arbitrary attributes.
+  const value = {
+    action: audit.action, approvalReference: audit.approvalReference ?? null,
+    authorityMode: audit.authorityMode, correlationId: audit.correlationId,
+    decision: audit.decision, delegationReference: audit.delegationReference ?? null,
+    policyVersion: audit.policyVersion, principalKind: audit.principalKind,
+    pseudonymousSubjectId: audit.pseudonymousSubjectId, reasonCategory: audit.reasonCategory,
+    resourceReference: audit.resourceReference ?? null, resourceType: audit.resourceType,
+    slice: audit.slice, stage: audit.stage, subjectType: audit.subjectType, timestamp: audit.timestamp,
+  };
+  await dataStore().commit({ tenantId: 'application', changes: [{ action: 'put', collection: 'authorization-audit', id: randomUUID(), expectedVersion: 0, value }] });
+}
+`);
+}
+function renderDynamoAuthorizationStore(pascalName) {
+    return `import type { ApprovalRequest, DelegationGrant, DelegationStore } from '@empire-builder-kit/runtime/authorization';
+import { dataStore } from '../data/key-value.js';
+import type { ${pascalName}AuthorizationAction } from './policy.js';
+
+function conditionalConflict(error: unknown): boolean {
+  if (!(error instanceof Error) || error.name !== 'TransactionCanceledException') return false;
+  return (error as Error & { CancellationReasons?: { Code?: string }[] }).CancellationReasons?.some(({ Code }) => Code === 'ConditionalCheckFailed') === true;
+}
+
+function revisionStore<T extends { id: string; revision: number }>(collection: string) {
+  async function save(id: string, expectedRevision: number | null, value: T): Promise<boolean> {
+    if (value.id !== id || !Number.isSafeInteger(value.revision) || value.revision !== (expectedRevision === null ? 0 : expectedRevision + 1) || (expectedRevision !== null && (!Number.isSafeInteger(expectedRevision) || expectedRevision < 0)))
+      throw new Error('Authorization state requires an exact monotonic revision.');
+    try {
+      await dataStore().commit({ tenantId: 'application', changes: [{ action: 'put', collection, id, expectedVersion: expectedRevision === null ? 0 : expectedRevision + 1, value }] });
+      return true;
+    } catch (error) {
+      if (conditionalConflict(error)) return false;
+      throw error;
+    }
+  }
+  return {
+    create: (value: T) => save(value.id, null, value),
+    async read(id: string): Promise<T | undefined> {
+      const item = await dataStore().get('application', collection, id);
+      if (!item) return undefined;
+      const value = item.value as T;
+      if (!value || value.id !== id || !Number.isSafeInteger(value.revision) || value.revision < 0 || item.version !== value.revision + 1)
+        throw new Error('Stored authorization revision is invalid.');
+      return value;
+    },
+    write: (id: string, expectedRevision: number, value: T) => save(id, expectedRevision, value),
+  };
+}
+
+export function create${pascalName}DelegationStore(_correlationId: string): DelegationStore<${pascalName}AuthorizationAction> {
+  void _correlationId; // Correlation is carried by the caller's audit, not store identity.
+  return revisionStore<DelegationGrant<${pascalName}AuthorizationAction>>('delegation-grants');
+}
+
+export interface ${pascalName}ApprovalStore {
+  create(request: ApprovalRequest<${pascalName}AuthorizationAction>): Promise<boolean>;
+  read(requestId: string): Promise<ApprovalRequest<${pascalName}AuthorizationAction> | undefined>;
+  write(requestId: string, expectedRevision: number, request: ApprovalRequest<${pascalName}AuthorizationAction>): Promise<boolean>;
+}
+
+export function create${pascalName}ApprovalStore(_correlationId: string): ${pascalName}ApprovalStore {
+  void _correlationId;
+  return revisionStore<ApprovalRequest<${pascalName}AuthorizationAction>>('approval-requests');
+}
+`;
+}
+//# sourceMappingURL=built-in-plan-authorization-storage.js.map

package/src/generators/slice/built-in-plan-background-work-files.d.ts

@@ -0,0 +1,2 @@
+import { type DeploymentProfile } from '../../repository-policy/index.js';
+export declare function renderBackgroundWorkFiles(profile: DeploymentProfile, sql?: boolean): Readonly<Record<string, string>>;

package/src/generators/slice/built-in-plan-background-work-files.js

@@ -0,0 +1,99 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.renderBackgroundWorkFiles = renderBackgroundWorkFiles;
+const index_js_1 = require("../../repository-policy/index.js");
+const built_in_plan_shared_js_1 = require("./built-in-plan-shared.js");
+function renderBackgroundWorkFiles(profile, sql = false) {
+    const stages = (0, index_js_1.activeDeploymentStages)(profile);
+    return {
+        'operations/background-work.json': (0, built_in_plan_shared_js_1.json)({
+            schemaVersion: 1,
+            stages: Object.fromEntries(stages.map((stage) => [
+                stage,
+                {
+                    outbox: {
+                        enabled: true,
+                        cadence: stage === 'production' ? 'rate(1 minute)' : 'rate(15 minutes)',
+                    },
+                    ...(sql
+                        ? {
+                            sqlOutboxRecovery: { enabled: true, cadence: 'rate(1 hour)' },
+                        }
+                        : {}),
+                    inboxCleanup: { enabled: true, cadence: 'rate(1 hour)' },
+                    exportCleanup: { enabled: true, cadence: 'rate(1 hour)' },
+                    retention: { enabled: true, cadence: 'rate(1 day)' },
+                },
+            ])),
+        }),
+        'infra/background-work.ts': `const activeStages: readonly string[] = ${JSON.stringify(stages)};
+const jobs = ['outbox', 'inboxCleanup', 'exportCleanup', 'retention'${sql ? ", 'sqlOutboxRecovery'" : ''}] as const;
+type Job = (typeof jobs)[number];
+type Schedule = { scheduleExpression: string; state: 'ENABLED' | 'DISABLED' };
+
+function record(value: unknown, label: string): Record<string, unknown> {
+  if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+    throw new Error('operations/background-work.json: invalid ' + label);
+  }
+  return value as Record<string, unknown>;
+}
+
+export function backgroundWorkSchedules(value: unknown, stage: string): Record<Job, Schedule> {
+  if (!activeStages.includes(stage)) throw new Error('Background work requested for inactive stage: ' + stage);
+  const policy = record(value, 'policy');
+  if (policy.schemaVersion !== 1 || Object.keys(policy).some((key) => !['schemaVersion', 'stages'].includes(key))) {
+    throw new Error('operations/background-work.json requires schemaVersion 1');
+  }
+  const configuredStages = record(policy.stages, 'stages');
+  if (Object.keys(configuredStages).length !== activeStages.length || Object.keys(configuredStages).some((key) => !activeStages.includes(key))) {
+    throw new Error('Background work must configure exactly the active stages');
+  }
+  const schedules: Record<string, Record<Job, Schedule>> = {};
+  for (const activeStage of activeStages) {
+    const configured = record(configuredStages[activeStage], activeStage);
+    if (Object.keys(configured).length !== jobs.length || Object.keys(configured).some((key) => !(jobs as readonly string[]).includes(key))) {
+      throw new Error('Background work must declare each supported job for ' + activeStage);
+    }
+    const result = {} as Record<Job, Schedule>;
+    for (const job of jobs) {
+      const entry = record(configured[job], activeStage + '/' + job);
+      const cadence = entry.cadence;
+      const match = typeof cadence === 'string' ? /^rate\\(([1-9][0-9]{0,3}) (minute|hour|day)(s?)\\)$/.exec(cadence) : null;
+      if (typeof entry.enabled !== 'boolean' || Object.keys(entry).some((key) => !['enabled', 'cadence'].includes(key)) || !match || (Number(match[1]) === 1 ? match[3] !== '' : match[3] !== 's') || Number(match[1]) > 1440) {
+        throw new Error('Invalid background work configuration for ' + activeStage + '/' + job + '; use enabled boolean and a bounded rate cadence');
+      }
+      result[job] = { scheduleExpression: cadence as string, state: entry.enabled ? 'ENABLED' : 'DISABLED' };
+    }
+    schedules[activeStage] = result;
+  }
+  return schedules[stage];
+}
+`,
+        'docs/runbooks/background-work.md': `# Background work and idle capacity
+
+Edit seeded \`operations/background-work.json\` to change cadence or explicitly
+pause outbox processing, inbox cleanup, export cleanup, or retention per active
+stage. Each entry requires \`enabled\` and \`cadence\` (a rate from 1 to 1440
+minutes, hours, or days with correct pluralization).
+Default DynamoDB outbox recovery runs every minute in production and every fifteen
+minutes in nonproduction. Its cadence and pause never control SQL recovery.
+${sql ? 'The separate sqlOutboxRecovery entry defaults to hourly missed-notification recovery; normal SQL delivery is driven by after-commit notifications. Pausing that entry pauses both SQL notification delivery and recovery, without pausing DynamoDB processing.' : ''}
+Inbox/export cleanup remains hourly and retention daily. Existing explicit
+cadences and pauses are seeded decisions and survive upgrades, including later
+SQL declaration. When SQL is added, its new recovery entry inherits an explicit
+outbox pause but not the DynamoDB cadence; review and resume it deliberately.
+
+Capacity profiles do not pause background work. A schedule can keep an Aurora
+cluster awake even when its minimum capacity is zero. Pausing outbox processing
+delays event delivery and accumulates a backlog; pausing cleanup defers expiry
+and retention work. Resume deliberately by setting enabled to true, reviewing
+the backlog and cleanup impact, and deploying through the normal lifecycle.
+Generation and upgrades retain these decisions. Rule identities, targets,
+permissions, backups, encryption, and deletion protection do not change.
+
+A source edit does not change AWS. Retain any maintenance deployment hold until
+source and live schedules have been reconciled under the approved procedure.
+`,
+    };
+}
+//# sourceMappingURL=built-in-plan-background-work-files.js.map