@empire-builder-kit/nx 1.0.0-rc.37 → 1.0.0-rc.39

package/src/generators/slice/built-in-plan-key-value-holds.js

@@ -0,0 +1,189 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.renderKeyValueHoldFiles = renderKeyValueHoldFiles;
+/** Native data-rights holds. The versioned per-record set closes absent-hold races. */
+function renderKeyValueHoldFiles(name, pascalName) {
+    return {
+        'data/data-rights-shared.ts': `import { randomUUID } from 'node:crypto';
+import type { AuthorizationPrincipal } from '@empire-builder-kit/runtime/authorization';
+import type { KeyValueChange } from '@empire-builder-kit/runtime/key-value';
+import { createDataLifecycleAuditRecord, createDataLifecyclePseudonymousReference,
+  type DataLifecycleAuditAction, type DataLifecycleEvidenceOutcome } from '@empire-builder-kit/runtime/data-lifecycle';
+import { approvalReference, productRecordReference } from './pseudonymous-reference.js';
+import { ${pascalName}DataLifecycleRuntimePolicy } from './runtime-policy.cjs';
+
+export const DATA_RIGHTS_POLICY_VERSION = ${pascalName}DataLifecycleRuntimePolicy.policyVersion;
+export const DATA_RIGHTS_AUDIT_RETENTION_DAYS = 400;
+export function canonicalDataRightsNow(now?: string): string {
+  const value = now ?? new Date().toISOString();
+  if (typeof value !== 'string' || !Number.isFinite(Date.parse(value)) || new Date(value).toISOString() !== value)
+    throw new Error('Data-rights time must be a canonical ISO-8601 timestamp.');
+  return value;
+}
+export const plusDataRightsDays = (value: string, days: number) => new Date(Date.parse(value) + days * 86_400_000).toISOString();
+export const plusDataRightsHours = (value: string, hours: number) => new Date(Date.parse(value) + hours * 3_600_000).toISOString();
+export const dataRightsSubjectReference = (value: string) => createDataLifecyclePseudonymousReference({ categoryId: 'authorization-subject', slice: '${name}', value });
+export const dataRightsCorrelationReference = (value: string) => createDataLifecyclePseudonymousReference({ categoryId: 'correlation', slice: '${name}', value });
+export const dataRightsArtifactReference = (value: string) => createDataLifecyclePseudonymousReference({ categoryId: 'subject-export', slice: '${name}', value });
+export function requireDirectHuman(principal: AuthorizationPrincipal): AuthorizationPrincipal {
+  if (principal.actor.type !== 'user' || principal.subject.type !== 'user' ||
+      principal.actor.id !== principal.subject.id || principal.authority.mode !== 'direct')
+    throw new Error('Data-rights request requires a direct human principal.');
+  return principal;
+}
+export function requireDirectAdmin(principal: AuthorizationPrincipal): AuthorizationPrincipal {
+  requireDirectHuman(principal);
+  if (principal.kind !== 'admin') throw new Error('Data-rights administration requires a direct admin.');
+  return principal;
+}
+export function requireExportCleanupAuthority(principal: AuthorizationPrincipal): AuthorizationPrincipal {
+  if (principal.authority.mode === 'machine' && principal.actor.type === 'service' &&
+      principal.subject.type === 'service' && principal.actor.id === '${name}:data-export-cleanup' &&
+      principal.subject.id === principal.actor.id && principal.audience === principal.actor.id &&
+      principal.authority.machineIdentityId === principal.actor.id) return principal;
+  return requireDirectAdmin(principal);
+}
+export { effectiveRecordOwner } from './records.js';
+
+/** Include this returned change in the same transaction as the protected effect. */
+export function dataRightsAuditChange(input: {
+  action: DataLifecycleAuditAction; approvalRequestId?: string; correlationId: string; now: string;
+  outcome: DataLifecycleEvidenceOutcome; principal: AuthorizationPrincipal; purposeCode: string;
+  recordId?: string; resourceReference?: string; summary: string;
+}): KeyValueChange {
+  const resourceReference = input.resourceReference ?? (input.recordId ? productRecordReference(input.recordId) : undefined);
+  if (!resourceReference) throw new Error('Data-rights audit requires a resource reference.');
+  const audit = createDataLifecycleAuditRecord({ action: input.action,
+    actorRef: dataRightsSubjectReference(input.principal.actor.id), authorityCode: input.principal.authority.mode,
+    correlationRef: dataRightsCorrelationReference(input.correlationId), outcome: input.outcome,
+    policyVersion: DATA_RIGHTS_POLICY_VERSION, purposeCode: input.purposeCode,
+    summary: input.summary, targetCategoryId: 'product-record', timestamp: canonicalDataRightsNow(input.now) });
+  return { action: 'put', collection: 'data-lifecycle-audit', id: randomUUID(), expectedVersion: 0,
+    value: { audit, resourceReference, approvalReference: input.approvalRequestId ? approvalReference(input.approvalRequestId) : null,
+      principalKind: input.principal.kind, subjectType: input.principal.actor.type,
+      slice: '${name}', stage: process.env.EBK_STAGE,
+      expiresAt: plusDataRightsDays(input.now, DATA_RIGHTS_AUDIT_RETENTION_DAYS) } };
+}
+`,
+        'data/record-holds.ts': `import { randomUUID } from 'node:crypto';
+import type { AuthorizationPrincipal } from '@empire-builder-kit/runtime/authorization';
+import type { KeyValueChange } from '@empire-builder-kit/runtime/key-value';
+import { evaluateDataLifecycleHolds, normalizeDataLifecycleRuntimeHold,
+  type DataLifecycleRuntimeHoldEffect, type DataLifecycleRuntimeHoldPurpose,
+  type DataLifecycleRuntimeHoldV1 } from '@empire-builder-kit/runtime/data-lifecycle';
+import { productRecordReference } from './pseudonymous-reference.js';
+import { canonicalDataRightsNow, requireDirectAdmin, dataRightsAuditChange } from './data-rights-shared.js';
+import { ${pascalName}DataLifecycleRuntimePolicy } from './runtime-policy.cjs';
+import { dataStore } from './key-value.js';
+import { readProductRecord } from './records.js';
+
+const MAXIMUM_HOLD_LIFETIME_MS = 90 * 86_400_000;
+const MAXIMUM_RECORD_HOLDS = 64;
+interface HoldSet { scopeRef: string; holds: DataLifecycleRuntimeHoldV1[] }
+interface HoldCommand { correlationId: string; now?: string; principal: AuthorizationPrincipal; recordId: string }
+interface ExistingHoldCommand extends HoldCommand { holdId: string }
+function interval(startsAt: string, reviewAt: string, expiresAt: string) {
+  for (const value of [startsAt, reviewAt, expiresAt]) canonicalDataRightsNow(value);
+  if (Date.parse(startsAt) >= Date.parse(reviewAt) || Date.parse(reviewAt) > Date.parse(expiresAt) ||
+      Date.parse(expiresAt) - Date.parse(startsAt) > MAXIMUM_HOLD_LIFETIME_MS)
+    throw new Error('Record hold requires a future review and a lifetime of at most 90 days.');
+}
+export function createRecordHold(input: {
+  effects: readonly DataLifecycleRuntimeHoldEffect[]; expiresAt: string; principal: AuthorizationPrincipal;
+  purpose: DataLifecycleRuntimeHoldPurpose; recordId: string; reviewAt: string;
+}, now = canonicalDataRightsNow()): DataLifecycleRuntimeHoldV1 {
+  requireDirectAdmin(input.principal);
+  interval(now, input.reviewAt, input.expiresAt);
+  return normalizeDataLifecycleRuntimeHold({ categoryId: 'product-record', effects: [...input.effects],
+    expiresAt: input.expiresAt, holdId: 'hold.' + randomUUID().replaceAll('-', ''), issuerCode: 'direct-admin',
+    purpose: input.purpose, reviewAt: input.reviewAt, scopeRef: productRecordReference(input.recordId),
+    startsAt: now, status: 'active' }, 0);
+}
+async function holdSet(recordId: string) {
+  const scopeRef = productRecordReference(recordId);
+  const row = await dataStore().get('application', 'data-lifecycle-hold-sets', scopeRef);
+  const value = row?.value as HoldSet | undefined;
+  if (row && (!value || value.scopeRef !== scopeRef || !Array.isArray(value.holds) || value.holds.length > MAXIMUM_RECORD_HOLDS))
+    throw new Error('Stored hold set is malformed or belongs to another record.');
+  const holds = (value?.holds ?? []).map((hold, index) => normalizeDataLifecycleRuntimeHold(hold, index));
+  if (new Set(holds.map(hold => hold.holdId)).size !== holds.length || holds.some(hold =>
+      hold.scopeRef !== scopeRef || hold.categoryId !== 'product-record' || hold.status !== 'active' ||
+      Date.parse(hold.expiresAt) - Date.parse(hold.startsAt) > MAXIMUM_HOLD_LIFETIME_MS))
+    throw new Error('Stored hold set contains substituted, duplicate or invalid holds.');
+  return { scopeRef, holds, version: row?.version ?? 0 };
+}
+
+/** Callers must include check in the effect transaction, including when no hold exists. */
+export async function loadActiveRecordHolds(recordId: string, now: string, operation: 'deletion' | 'export') {
+  const retained = await holdSet(recordId);
+  const holds = [...${pascalName}DataLifecycleRuntimePolicy.declaredHolds, ...retained.holds];
+  const evaluation = evaluateDataLifecycleHolds({ categoryId: 'product-record', holds,
+    now: canonicalDataRightsNow(now), operation, scopeRef: retained.scopeRef });
+  const check: KeyValueChange = { action: 'check', collection: 'data-lifecycle-hold-sets',
+    id: retained.scopeRef, expectedVersion: retained.version };
+  return { holds, evaluation, check };
+}
+async function persist(input: HoldCommand, now: string, hold: DataLifecycleRuntimeHoldV1,
+  currentVersion: number, set: Awaited<ReturnType<typeof holdSet>>, purposeCode: string) {
+  const store = dataStore();
+  const record = await store.get('application', 'records', input.recordId);
+  if (!record) throw new Error('The held record was not found.');
+  readProductRecord(record.value, input.recordId);
+  const holds = set.holds.filter(item => item.holdId !== hold.holdId);
+  if (hold.status === 'active') holds.push(hold);
+  if (holds.length > MAXIMUM_RECORD_HOLDS) throw new Error('Record has 64 active holds; explicitly close due holds before issuing another.');
+  holds.sort((a, b) => a.holdId < b.holdId ? -1 : a.holdId > b.holdId ? 1 : 0);
+  await store.commit({ tenantId: 'application', changes: [
+    { action: 'check', collection: 'records', id: input.recordId, expectedVersion: record.version },
+    { action: 'put', collection: 'data-lifecycle-hold-sets', id: set.scopeRef,
+      expectedVersion: set.version, value: { scopeRef: set.scopeRef, holds } },
+    { action: 'put', collection: 'data-lifecycle-holds', id: hold.holdId, expectedVersion: currentVersion, value: hold },
+    dataRightsAuditChange({ action: 'hold', correlationId: input.correlationId, now, outcome: 'succeeded',
+      principal: input.principal, purposeCode, recordId: input.recordId, summary: 'A bounded record hold transition was committed.' }),
+  ] });
+  return hold;
+}
+export async function issueRecordHold(input: HoldCommand & {
+  effects: readonly DataLifecycleRuntimeHoldEffect[]; expiresAt: string; purpose: DataLifecycleRuntimeHoldPurpose; reviewAt: string;
+}) {
+  const now = canonicalDataRightsNow(input.now);
+  const hold = createRecordHold(input, now);
+  return persist(input, now, hold, 0, await holdSet(input.recordId), 'hold-issue');
+}
+async function current(input: ExistingHoldCommand) {
+  requireDirectAdmin(input.principal);
+  const now = canonicalDataRightsNow(input.now);
+  const set = await holdSet(input.recordId);
+  const row = await dataStore().get('application', 'data-lifecycle-holds', input.holdId);
+  if (!row) throw new Error('The record hold was not found.');
+  const hold = normalizeDataLifecycleRuntimeHold(row.value as DataLifecycleRuntimeHoldV1, 0);
+  const indexed = set.holds.find(value => value.holdId === input.holdId);
+  if (hold.holdId !== input.holdId || hold.scopeRef !== set.scopeRef || hold.categoryId !== 'product-record' ||
+      hold.status !== 'active' || !indexed || JSON.stringify(indexed) !== JSON.stringify(hold))
+    throw new Error('The active record hold and its set do not agree.');
+  return { now, set, hold, version: row.version };
+}
+export async function reviewRecordHold(input: ExistingHoldCommand & { expiresAt: string; reviewAt: string }) {
+  const { now, set, hold, version } = await current(input);
+  if (Date.parse(now) >= Date.parse(hold.expiresAt)) throw new Error('Only an unexpired active hold can be reviewed.');
+  interval(hold.startsAt, input.reviewAt, input.expiresAt);
+  if (Date.parse(input.reviewAt) <= Date.parse(now)) throw new Error('Reviewed hold must set a future review time.');
+  const reviewed = normalizeDataLifecycleRuntimeHold({ ...hold, reviewAt: input.reviewAt, expiresAt: input.expiresAt }, 0);
+  return persist(input, now, reviewed, version, set, 'hold-review');
+}
+export async function releaseRecordHold(input: ExistingHoldCommand) {
+  const { now, set, hold, version } = await current(input);
+  if (Date.parse(now) >= Date.parse(hold.expiresAt)) throw new Error('Use explicit expiry for a due record hold.');
+  const released = normalizeDataLifecycleRuntimeHold({ ...hold, releasedAt: now, status: 'released' }, 0);
+  return persist(input, now, released, version, set, 'hold-release');
+}
+export async function expireRecordHold(input: ExistingHoldCommand) {
+  const { now, set, hold, version } = await current(input);
+  if (Date.parse(now) < Date.parse(hold.expiresAt)) throw new Error('Record hold is not due for expiry.');
+  const expired = normalizeDataLifecycleRuntimeHold({ ...hold, releasedAt: hold.expiresAt, status: 'released' }, 0);
+  return persist(input, now, expired, version, set, 'hold-expiry');
+}
+`,
+    };
+}
+//# sourceMappingURL=built-in-plan-key-value-holds.js.map

package/src/generators/slice/built-in-plan-key-value-infrastructure.d.ts

@@ -0,0 +1,2 @@
+/** Slice/task-owned resources. No VPC, shared table, pre-created role, or SQL dependency. */
+export declare function renderKeyValueInfrastructureFiles(name: string, pascalName: string): Readonly<Record<string, string>>;

package/src/generators/slice/built-in-plan-key-value-infrastructure.js

@@ -0,0 +1,102 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.renderKeyValueInfrastructureFiles = renderKeyValueInfrastructureFiles;
+/** Slice/task-owned resources. No VPC, shared table, pre-created role, or SQL dependency. */
+function renderKeyValueInfrastructureFiles(name, pascalName) {
+    return {
+        'infra/key-value.ts': `export function createKeyValueInfrastructure(input: {
+  eventBusArn: any;
+  eventBusName: any;
+  alertTopicArn: any;
+  outbox: { scheduleExpression: string; state: 'ENABLED' | 'DISABLED' };
+  managedLogGroup(logicalName: string, component: string, alertTopicArn: any): { logGroup: { name: any } };
+  lambdaLogging(logGroupName: any): { logging: any; transform: any };
+}) {
+  const production = $app.stage === 'production';
+  const tags = { 'ebk:slice': '${name}', 'ebk:stage': $app.stage, 'ebk:persistence': 'key-value' };
+  const table = new aws.dynamodb.Table('${pascalName}KeyValue', {
+    name: '${name}-' + $app.stage + '-key-value',
+    billingMode: 'PAY_PER_REQUEST', hashKey: 'pk', rangeKey: 'sk',
+    attributes: [
+      { name: 'pk', type: 'S' }, { name: 'sk', type: 'S' },
+      { name: 'pendingPk', type: 'S' }, { name: 'pendingAt', type: 'N' },
+    ],
+    globalSecondaryIndexes: [{ name: 'PendingEvents', hashKey: 'pendingPk', rangeKey: 'pendingAt', projectionType: 'ALL' }],
+    streamEnabled: true, streamViewType: 'NEW_AND_OLD_IMAGES',
+    ttl: { attributeName: 'expiresAt', enabled: true },
+    pointInTimeRecovery: { enabled: true, recoveryPeriodInDays: 35 },
+    serverSideEncryption: { enabled: true },
+    deletionProtectionEnabled: production,
+    tags,
+  }, { protect: production, retainOnDelete: production });
+  const environment = {
+    EBK_STAGE: $app.stage, EBK_KEY_VALUE_TABLE: table.name,
+    EVENT_BUS_NAME: input.eventBusName,
+  };
+  const indexArn = table.arn.apply((arn: string) => arn + '/index/PendingEvents');
+  const dataPermissions = [{
+    // DynamoDB transactions authorize their constituent item operations.
+    actions: ['dynamodb:GetItem', 'dynamodb:PutItem', 'dynamodb:UpdateItem', 'dynamodb:DeleteItem', 'dynamodb:ConditionCheckItem', 'dynamodb:Query'],
+    resources: [table.arn],
+  }];
+  const link = new sst.Linkable('${pascalName}KeyValueAccess', {
+    properties: { tableName: table.name },
+    include: dataPermissions.map((permission) => sst.aws.permission(permission)),
+  });
+  const streamPermissions = [{
+    actions: ['dynamodb:DescribeStream', 'dynamodb:GetRecords', 'dynamodb:GetShardIterator', 'dynamodb:ListStreams'],
+    resources: [table.streamArn],
+  }];
+  const deliveryPermissions = [
+    { actions: ['dynamodb:GetItem', 'dynamodb:UpdateItem'], resources: [table.arn] },
+    { actions: ['events:PutEvents'], resources: [input.eventBusArn] },
+  ];
+  // SST creates these roles; the workspace's stage-boundary transform still applies.
+  const dispatcherLogs = input.managedLogGroup('${pascalName}KeyValueStreamDeliveryLogs', 'key-value-stream-delivery', input.alertTopicArn);
+  const dispatcher = new sst.aws.Function('${pascalName}KeyValueStreamDelivery', {
+    handler: 'async/key-value-delivery.stream', dev: false,
+    environment: { ...environment, EBK_KEY_VALUE_STREAM_ARN: table.streamArn },
+    permissions: [...deliveryPermissions, ...streamPermissions],
+    timeout: '5 minutes', ...input.lambdaLogging(dispatcherLogs.logGroup.name),
+  });
+  const mapping = new aws.lambda.EventSourceMapping('${pascalName}KeyValueStreamMapping', {
+    eventSourceArn: table.streamArn, functionName: dispatcher.arn,
+    enabled: input.outbox.state === 'ENABLED', startingPosition: 'TRIM_HORIZON',
+    batchSize: 100, maximumBatchingWindowInSeconds: 1,
+    functionResponseTypes: ['ReportBatchItemFailures'], bisectBatchOnFunctionError: true,
+    maximumRetryAttempts: 3, maximumRecordAgeInSeconds: 3600,
+    filterCriteria: { filters: [{ pattern: JSON.stringify({
+      eventName: ['INSERT'], dynamodb: { NewImage: { kind: { S: ['outbox'] }, state: { S: ['pending'] } } },
+    }) }] },
+  });
+  const reconcilerLogs = input.managedLogGroup('${pascalName}KeyValueReconciliationLogs', 'key-value-reconciliation', input.alertTopicArn);
+  const reconciler = new sst.aws.Function('${pascalName}KeyValueReconciliation', {
+    handler: 'async/key-value-delivery.reconcile', dev: false, environment,
+    permissions: [...deliveryPermissions,
+      { actions: ['dynamodb:PutItem', 'dynamodb:DeleteItem'], resources: [table.arn] },
+      // Published intents leave the index; bounded deletion completion scans
+      // its own table collection using an independent persisted cursor.
+      { actions: ['dynamodb:Query'], resources: [table.arn, indexArn] },
+    ],
+    // Per-intent leases and versioned checkpoints, not account concurrency
+    // reservations, coordinate overlapping reconciliation invocations.
+    timeout: '15 minutes',
+    ...input.lambdaLogging(reconcilerLogs.logGroup.name),
+  });
+  const rule = new aws.cloudwatch.EventRule('${pascalName}KeyValueReconciliationSchedule', {
+    ...input.outbox, description: 'Bounded recovery of durable event intents, independent of stream retention.', tags,
+  });
+  const permission = new aws.lambda.Permission('${pascalName}KeyValueReconciliationPermission', {
+    action: 'lambda:InvokeFunction', function: reconciler.arn,
+    principal: 'events.amazonaws.com', sourceArn: rule.arn,
+  });
+  const target = new aws.cloudwatch.EventTarget('${pascalName}KeyValueReconciliationTarget', {
+    arn: reconciler.arn, rule: rule.name,
+    retryPolicy: { maximumEventAgeInSeconds: 3600, maximumRetryAttempts: 2 },
+  }, { dependsOn: [permission] });
+  return { table, link, environment, dataPermissions, dispatcher, mapping, reconciler, rule, target };
+}
+`,
+    };
+}
+//# sourceMappingURL=built-in-plan-key-value-infrastructure.js.map

package/src/generators/slice/built-in-plan-key-value-performance.d.ts

@@ -0,0 +1,5 @@
+/** Protected test effects use native collections, never the application's records. */
+export declare function renderKeyValuePerformanceFiles(name: string): Readonly<Record<string, string>>;
+export declare function renderKeyValueOutboxTests(): string;
+/** The common protected HTTP shell owns HMAC, release, target and body limits. */
+export declare function renderKeyValuePerformanceEndpointFunctions(): string;