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

package/src/foundation/local-private-smoke-access.js

@@ -0,0 +1,197 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runLocalPrivateSmoke = runLocalPrivateSmoke;
+const client_cloudfront_1 = require("@aws-sdk/client-cloudfront");
+const client_wafv2_1 = require("@aws-sdk/client-wafv2");
+const credential_providers_1 = require("@aws-sdk/credential-providers");
+const node_crypto_1 = require("node:crypto");
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const process_identity_js_1 = require("../local-dev/process-identity.js");
+const fleet_lock_js_1 = require("../local-dev/fleet-lock.js");
+const private_state_js_1 = require("../local-dev/private-state.js");
+const index_js_1 = require("../repository-policy/index.js");
+const federated_credential_transport_js_1 = require("../executors/local-deploy/federated-credential-transport.js");
+const router_waf_js_1 = require("./router-waf.js");
+const private_smoke_control_plane_js_1 = require("./private-smoke-control-plane.js");
+const private_smoke_admission_js_1 = require("./private-smoke-admission.js");
+function check(value, message) {
+    if (!value)
+        throw new Error(`Local private smoke: ${message}`);
+}
+/** Used after the local lifecycle verifies source, policy and federated role.
+ * A private process receipt proves recovery ownership, not deployment authority. */
+async function runLocalPrivateSmoke(input, dependencies = {}) {
+    check(!(0, index_js_1.requiresGithubDeployment)(input.deploymentProfile, input.stage), 'stage requires protected GitHub authority');
+    const policy = (0, router_waf_js_1.normalizeRouterWafPolicy)(JSON.parse((0, node_fs_1.readFileSync)((0, node_path_1.join)(input.root, 'packages/foundation/security/router-waf.json'), 'utf8')));
+    check(policy.deploymentProfile === input.deploymentProfile, 'deployment profile differs');
+    const stagePolicy = policy.stages[input.stage];
+    check(stagePolicy, 'stage is inactive');
+    if (stagePolicy.access === 'public' || stagePolicy.mode === 'count') {
+        await input.run();
+        return;
+    }
+    const allowedCidrs = stagePolicy.allowedCidrs.filter((cidr) => !cidr.includes(':'));
+    // Temporary admission has its own empty set; never update the baseline.
+    const baseline = [];
+    check(/^(?:[a-f0-9]{40}|[a-f0-9]{64})$/.test(input.source), 'source identity is invalid');
+    const policyDigest = (0, router_waf_js_1.routerWafPolicyDigest)(policy);
+    const identity = {
+        account: input.account,
+        stage: input.stage,
+        workspace: input.workspace,
+        policyDigest,
+    };
+    const open = dependencies.open ??
+        (async (resourceIdentity, url) => {
+            const environment = input.credentialEnvironment;
+            check(environment.AWS_PROFILE &&
+                environment.AWS_CONFIG_FILE &&
+                environment.AWS_SHARED_CREDENTIALS_FILE, 'verified private credential transport is missing');
+            const credentials = (0, credential_providers_1.fromIni)({
+                profile: environment.AWS_PROFILE,
+                configFilepath: environment.AWS_CONFIG_FILE,
+                filepath: environment.AWS_SHARED_CREDENTIALS_FILE,
+                // The invocation refreshes this same file before smoke. Ownership
+                // checks may already have populated Smithy's shared ini-file cache.
+                ignoreCache: true,
+            });
+            const options = {
+                credentials,
+                region: 'us-east-1',
+                maxAttempts: 3,
+                requestHandler: { connectionTimeout: 10_000, requestTimeout: 30_000 },
+            };
+            return (0, private_smoke_control_plane_js_1.openPrivateSmokeControlPlane)(resourceIdentity, url, {
+                waf: new client_wafv2_1.WAFV2Client({
+                    ...options,
+                    endpoint: 'https://wafv2.us-east-1.amazonaws.com',
+                }),
+                cloudfront: new client_cloudfront_1.CloudFrontClient({
+                    ...options,
+                    endpoint: 'https://cloudfront.amazonaws.com',
+                }),
+            });
+        });
+    const store = await open(identity, input.url);
+    const request = dependencies.fetch ?? fetch;
+    const wait = dependencies.wait ??
+        ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
+    const path = (0, node_path_1.join)((0, node_fs_1.realpathSync)(input.root), '.ebk/evidence/local-smoke', `${input.stage}.json`);
+    const security = dependencies.security;
+    const readOwner = () => {
+        const value = JSON.parse((0, private_state_js_1.readPrivateFile)(path, security).toString('utf8'));
+        check(value?.kind === 'ebk-local-smoke-owner' &&
+            value.schemaVersion === 1 &&
+            value.account === input.account &&
+            value.stage === input.stage &&
+            value.workspace === input.workspace &&
+            value.policyDigest === policyDigest, 'retained owner or policy differs; preserve recovery evidence');
+        (0, fleet_lock_js_1.validateFleetProcessIdentity)(value.owner);
+        check(value.context?.authority === 'local' &&
+            /^[a-f0-9]{32}$/.test(value.context.run) &&
+            /^[1-9]\d*$/.test(value.context.attempt) &&
+            /^(?:[a-f0-9]{40}|[a-f0-9]{64})$/.test(value.context.source) &&
+            JSON.stringify(value.context.baseline) === JSON.stringify(baseline), 'retained admission context is invalid');
+        return value;
+    };
+    const releaseOwner = (expected) => {
+        check(JSON.stringify(readOwner()) === JSON.stringify(expected), 'private owner changed; cleanup not accepted');
+        const retired = `${path}.${expected.context.run}.completed`;
+        check(!(0, node_fs_1.existsSync)(retired), 'prior recovery completion is unresolved');
+        (0, node_fs_1.renameSync)(path, retired);
+        if ((0, private_state_js_1.readPrivateFile)(retired, security).toString('utf8') !==
+            JSON.stringify(expected)) {
+            if (!(0, node_fs_1.existsSync)(path))
+                (0, node_fs_1.renameSync)(retired, path);
+            throw new Error('Local private smoke: owner changed during retirement');
+        }
+        (0, node_fs_1.unlinkSync)(retired);
+    };
+    if ((0, node_fs_1.existsSync)(path)) {
+        (0, private_state_js_1.assertPrivatePath)((0, node_path_1.join)(input.root, '.ebk/evidence/local-smoke'), 'directory', security);
+        const previous = readOwner();
+        check((dependencies.probe ?? process_identity_js_1.probeProcessIdentity)(previous.owner) === 'absent', 'prior smoke process is active or ambiguous');
+        await (0, private_smoke_admission_js_1.recoverSmokeAdmission)(store, baseline, async (lease) => lease.authority === 'local' &&
+            lease.run === previous.context.run &&
+            lease.attempt === previous.context.attempt &&
+            lease.source === previous.context.source);
+        releaseOwner(previous);
+    }
+    else {
+        // Foreign/local-without-receipt and hosted leases must not be claimed.
+        await (0, private_smoke_admission_js_1.recoverSmokeAdmission)(store, baseline, async () => false);
+    }
+    const ipResponse = await request('https://checkip.amazonaws.com', {
+        redirect: 'error',
+        signal: AbortSignal.timeout(15_000),
+    });
+    check(ipResponse.ok, 'operator IPv4 lookup failed');
+    const address = await ipResponse.text();
+    check(address.length <= 64, 'operator IPv4 response exceeds bound');
+    const cidr = (0, private_smoke_admission_js_1.publicRunnerIpv4)(address.trim());
+    if ((0, private_smoke_admission_js_1.runnerAlreadyAllowed)(cidr, allowedCidrs)) {
+        await input.run();
+        return;
+    }
+    const owner = (dependencies.capture ?? process_identity_js_1.captureProcessIdentity)();
+    const context = {
+        authority: 'local',
+        run: (0, node_crypto_1.randomBytes)(16).toString('hex'),
+        attempt: String(owner.pid),
+        source: input.source,
+        baseline,
+    };
+    const record = {
+        kind: 'ebk-local-smoke-owner',
+        schemaVersion: 1,
+        ...identity,
+        owner,
+        context,
+    };
+    check((0, private_state_js_1.createPrivateFileExclusive)(path, JSON.stringify(record), security), 'another invocation owns local smoke');
+    async function observe(allowed, signal) {
+        for (let i = 0; i < 24; i++) {
+            signal?.throwIfAborted();
+            const response = await request(input.url, {
+                redirect: 'manual',
+                signal: signal
+                    ? AbortSignal.any([signal, AbortSignal.timeout(15_000)])
+                    : AbortSignal.timeout(15_000),
+            });
+            await response.body?.cancel();
+            if (allowed
+                ? response.status >= 200 && response.status < 400
+                : response.status === 403)
+                return;
+            if (i < 23)
+                await wait(5_000);
+        }
+        throw new Error(`Local private smoke: ${allowed ? 'admission' : 'revocation'} not observed; deployment acceptance prohibited`);
+    }
+    const unregister = (0, federated_credential_transport_js_1.registerGovernedSignalCleanup)(async () => {
+        await (0, private_smoke_admission_js_1.cleanupSmokeAdmission)(store, context);
+    }, 90);
+    try {
+        await (0, private_smoke_admission_js_1.withPrivateSmokeAdmission)({
+            store,
+            context,
+            cidr,
+            run: input.run,
+            awaitAdmission: (signal) => observe(true, signal),
+            awaitRevocation: () => observe(false),
+        });
+    }
+    finally {
+        try {
+            // A failed smoke may still have cleaned up correctly. Retain this receipt
+            // only when remote cleanup is unproved, for exact next-run recovery.
+            await (0, private_smoke_admission_js_1.cleanupSmokeAdmission)(store, context);
+            releaseOwner(record);
+        }
+        finally {
+            unregister();
+        }
+    }
+}
+//# sourceMappingURL=local-private-smoke-access.js.map

package/src/foundation/logging-preflight.js

@@ -13,7 +13,7 @@ function record(value) {
 }
 function stateResources(value) {
     const root = record(value);
-    const deployment = record(root?.deployment);
+    const deployment = record(root?.deployment) ?? record(root?.latest) ?? root;
     const resources = deployment?.resources ?? root?.resources;
     if (!Array.isArray(resources)) {
         throw new Error('SST state export does not contain a Pulumi deployment resource list.');

package/src/foundation/logging.d.ts

@@ -24,7 +24,9 @@ export interface ManagedLogGroupContract {
             {
                 DataIdentifier: string[];
                 Operation: {
-                    Audit: Record<string, never>;
+                    Audit: {
+                        FindingsDestination: Record<string, never>;
+                    };
                 };
                 Sid: 'AuditSensitiveData';
             },

package/src/foundation/logging.js

@@ -66,7 +66,7 @@ function createManagedLogGroupContract(input) {
             Statement: [
                 {
                     DataIdentifier: identifiers,
-                    Operation: { Audit: {} },
+                    Operation: { Audit: { FindingsDestination: {} } },
                     Sid: 'AuditSensitiveData',
                 },
                 {

package/src/foundation/partial-state.d.ts

@@ -0,0 +1,10 @@
+export declare const FOUNDATION_PENDING_DATABASE_ENDPOINT: "pending.invalid";
+/**
+ * Pulumi can evaluate a refresh program against an interrupted first deploy
+ * before the Aurora cluster has ever existed. SST currently resolves that
+ * absent endpoint as `undefined` and its Aurora link implementation calls
+ * `.split()` unconditionally. Keep the refresh program total without
+ * publishing a routable cross-stage value. A subsequent deploy receives the
+ * real provider output and replaces this sentinel before creating discovery.
+ */
+export declare function foundationDatabaseEndpointHost(endpoint: unknown): string;

package/src/foundation/partial-state.js

@@ -0,0 +1,21 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FOUNDATION_PENDING_DATABASE_ENDPOINT = void 0;
+exports.foundationDatabaseEndpointHost = foundationDatabaseEndpointHost;
+exports.FOUNDATION_PENDING_DATABASE_ENDPOINT = 'pending.invalid';
+/**
+ * Pulumi can evaluate a refresh program against an interrupted first deploy
+ * before the Aurora cluster has ever existed. SST currently resolves that
+ * absent endpoint as `undefined` and its Aurora link implementation calls
+ * `.split()` unconditionally. Keep the refresh program total without
+ * publishing a routable cross-stage value. A subsequent deploy receives the
+ * real provider output and replaces this sentinel before creating discovery.
+ */
+function foundationDatabaseEndpointHost(endpoint) {
+    if (typeof endpoint !== 'string') {
+        return exports.FOUNDATION_PENDING_DATABASE_ENDPOINT;
+    }
+    const host = endpoint.trim().split(':', 1)[0]?.trim() ?? '';
+    return host.length > 0 ? host : exports.FOUNDATION_PENDING_DATABASE_ENDPOINT;
+}
+//# sourceMappingURL=partial-state.js.map

package/src/foundation/preflight.js

@@ -73,19 +73,34 @@ async function evaluateFoundationPreflight(options) {
         result.invalidNames.forEach((name) => invalidNames.add(name));
         result.values.forEach((value, name) => values.set(name, value));
     }
+    const value = (key) => values.get((0, discovery_js_1.foundationSsmPath)(foundationStage, key)) ?? '';
+    const capabilities = value('capabilities')
+        .split(',')
+        .map((capability) => capability.trim())
+        .filter(Boolean);
+    const hasPostgres = capabilities.includes('postgres');
+    const resourceNames = (0, discovery_js_1.foundationSsmKeysForCapabilities)(capabilities.filter(requirements_js_1.isStandardFoundationCapability))
+        .map((key) => (0, discovery_js_1.foundationSsmPath)(foundationStage, key))
+        .filter((name) => !names.includes(name));
+    for (const batch of chunks(resourceNames, 10)) {
+        const result = await options.readParameters(batch);
+        result.invalidNames.forEach((name) => invalidNames.add(name));
+        result.values.forEach((value, name) => values.set(name, value));
+    }
+    names.push(...resourceNames);
     const issues = names
         .filter((name) => invalidNames.has(name) || !values.get(name))
         .map((name) => `missing required parameter ${name}`);
     const allRequiredParametersMissing = names.every((name) => invalidNames.has(name) || !values.has(name));
-    const value = (key) => values.get((0, discovery_js_1.foundationSsmPath)(foundationStage, key)) ?? '';
     const schemaVersion = Number(value('schemaVersion'));
     if (schemaVersion !== discovery_js_1.FOUNDATION_SSM_SCHEMA_VERSION) {
         issues.push(`Foundation discovery schema ${value('schemaVersion') || 'missing'} does not match ${discovery_js_1.FOUNDATION_SSM_SCHEMA_VERSION}`);
     }
     const databasePort = Number(value('databasePort'));
-    if (!Number.isSafeInteger(databasePort) ||
-        databasePort < 1 ||
-        databasePort > 65535) {
+    if (hasPostgres &&
+        (!Number.isSafeInteger(databasePort) ||
+            databasePort < 1 ||
+            databasePort > 65535)) {
         issues.push('Foundation discovery databasePort must be from 1 through 65535');
     }
     const accountMonthlyMaximumUsd = Number(value('accountMonthlyMaximumUsd'));
@@ -103,10 +118,6 @@ async function evaluateFoundationPreflight(options) {
     if (!isExactCognitoTokenEndpoint(value('identityTokenEndpoint'), options.region)) {
         issues.push('Foundation discovery identityTokenEndpoint must be the exact Cognito HTTPS token endpoint for the selected AWS Region');
     }
-    const capabilities = value('capabilities')
-        .split(',')
-        .map((capability) => capability.trim())
-        .filter(Boolean);
     const compatibility = (0, requirements_js_1.validateFoundationCompatibility)(options.requirement, {
         capabilities,
         contractVersion: value('contractVersion'),
@@ -128,15 +139,21 @@ async function evaluateFoundationPreflight(options) {
             accountMonthlyMaximumUsd,
             alertTopicArn: value('alertTopicArn'),
             capabilities: compatibility.value.capabilities,
-            clusterId: value('clusterId'),
+            ...(capabilities.includes('container-compute')
+                ? { clusterId: value('clusterId') }
+                : {}),
             contractVersion: compatibility.value.contractVersion,
-            databaseClusterArn: value('databaseClusterArn'),
-            databaseClusterEndpoint: value('databaseClusterEndpoint'),
-            databaseClusterId: value('databaseClusterId'),
-            databaseClusterResourceId: value('databaseClusterResourceId'),
-            databaseHost: value('databaseHost'),
-            databaseMasterSecretArn: value('databaseMasterSecretArn'),
-            databasePort,
+            ...(hasPostgres
+                ? {
+                    databaseClusterArn: value('databaseClusterArn'),
+                    databaseClusterEndpoint: value('databaseClusterEndpoint'),
+                    databaseClusterId: value('databaseClusterId'),
+                    databaseClusterResourceId: value('databaseClusterResourceId'),
+                    databaseHost: value('databaseHost'),
+                    databaseMasterSecretArn: value('databaseMasterSecretArn'),
+                    databasePort,
+                }
+                : {}),
             eventBusArn: value('eventBusArn'),
             eventBusName: value('eventBusName'),
             hasPublicDomain: value('hasPublicDomain') === 'true',
@@ -147,7 +164,7 @@ async function evaluateFoundationPreflight(options) {
             routerDistributionId: value('routerDistributionId'),
             routerUrl: value('routerUrl'),
             schemaVersion: discovery_js_1.FOUNDATION_SSM_SCHEMA_VERSION,
-            vpcId: value('vpcId'),
+            ...(capabilities.includes('network') ? { vpcId: value('vpcId') } : {}),
         },
         consumerStage,
         foundationStage,
@@ -163,7 +180,9 @@ function formatFoundationPreflightReport(report) {
     ];
     report.issues.forEach((issue) => lines.push(`  - ${issue}`));
     if (!report.ok) {
-        lines.push(`  Deploy the Foundation first: pnpm nx run foundation:deploy --stage=${report.foundationStage}`);
+        lines.push(report.foundationStage === 'development'
+            ? '  Establish Foundation through ebk deploy development --profile=<approved-profile> --expectedRoleArn=<approved-development-role>; the governed stage lifecycle deploys Foundation before eligible Slices.'
+            : `  Establish Foundation through the governed ${report.foundationStage} stage lifecycle under the repository deployment profile; follow its protected deployment runbook.`);
     }
     return lines.join('\n');
 }

package/src/foundation/private-smoke-access.d.ts

@@ -0,0 +1,25 @@
+import { openPrivateSmokeControlPlane } from './private-smoke-control-plane.js';
+import { type SmokeAdmissionLease } from './private-smoke-admission.js';
+import type { CanonicalDeploymentStage, DeploymentProfile } from '../repository-policy/index.js';
+export interface GithubPrivateSmokeInput {
+    account: string;
+    deploymentProfile: DeploymentProfile;
+    root: string;
+    source: string;
+    stage: CanonicalDeploymentStage;
+    url: string;
+    workspace: string;
+    /** Receives the admission lease when the runner was admitted; undefined when no admission was needed. */
+    run: (lease?: SmokeAdmissionLease) => Promise<void>;
+}
+interface PrivateSmokeDependencies {
+    environment?: NodeJS.ProcessEnv;
+    fetch?: typeof fetch;
+    open?: typeof openPrivateSmokeControlPlane;
+    wait?: (milliseconds: number) => Promise<void>;
+}
+/** Called only inside the source/role-verified protected stage lifecycle. */
+export declare function runGithubPrivateSmoke(input: GithubPrivateSmokeInput, dependencies?: PrivateSmokeDependencies): Promise<void>;
+/** Generated protected workflow finalizer. It can only remove an exact admission. */
+export declare function cleanupGithubPrivateSmoke(input: Omit<GithubPrivateSmokeInput, 'url' | 'run'>, dependencies?: PrivateSmokeDependencies): Promise<void>;
+export {};

package/src/foundation/private-smoke-access.js

@@ -0,0 +1,135 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runGithubPrivateSmoke = runGithubPrivateSmoke;
+exports.cleanupGithubPrivateSmoke = cleanupGithubPrivateSmoke;
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const router_waf_js_1 = require("./router-waf.js");
+const private_smoke_control_plane_js_1 = require("./private-smoke-control-plane.js");
+const private_smoke_admission_js_1 = require("./private-smoke-admission.js");
+function check(condition, message) {
+    if (!condition)
+        throw new Error(`Private smoke access: ${message}`);
+}
+/** Called only inside the source/role-verified protected stage lifecycle. */
+async function runGithubPrivateSmoke(input, dependencies = {}) {
+    return privateSmokeOperation(input, dependencies, false);
+}
+/** Generated protected workflow finalizer. It can only remove an exact admission. */
+async function cleanupGithubPrivateSmoke(input, dependencies = {}) {
+    return privateSmokeOperation({ ...input, url: '', run: async () => undefined }, dependencies, true);
+}
+async function privateSmokeOperation(input, dependencies, cleanupOnly) {
+    const environment = dependencies.environment ?? process.env;
+    const request = dependencies.fetch ?? fetch;
+    const policy = (0, router_waf_js_1.normalizeRouterWafPolicy)(JSON.parse((0, node_fs_1.readFileSync)((0, node_path_1.join)(input.root, 'packages/foundation/security/router-waf.json'), 'utf8')));
+    check(policy.deploymentProfile === input.deploymentProfile, 'WAF deployment profile differs from repository policy');
+    const stagePolicy = policy.stages[input.stage];
+    check(stagePolicy, 'inactive WAF stage');
+    if (stagePolicy.access === 'public' || stagePolicy.mode === 'count') {
+        await input.run();
+        return;
+    }
+    const allowedCidrs = stagePolicy.allowedCidrs.filter((cidr) => !cidr.includes(':'));
+    // Temporary admission has its own empty set; never update the baseline.
+    const baseline = [];
+    const repository = environment.GITHUB_REPOSITORY ?? '';
+    const ref = `refs/heads/${input.stage === 'production' ? 'main' : 'develop'}`;
+    const workflow = `${repository}/.github/workflows/deploy.yml@${ref}`;
+    check(environment.GITHUB_ACTIONS === 'true' &&
+        /^[\w.-]+\/[\w.-]+$/.test(repository) &&
+        environment.GITHUB_REF === ref &&
+        environment.GITHUB_SHA === input.source &&
+        environment.EBK_GITHUB_JOB_WORKFLOW_REF === workflow &&
+        ((environment.GITHUB_EVENT_NAME === 'workflow_dispatch' &&
+            environment.GITHUB_WORKFLOW_REF === workflow) ||
+            (environment.GITHUB_EVENT_NAME === 'push' &&
+                input.deploymentProfile !== 'starter' &&
+                environment.GITHUB_WORKFLOW_REF ===
+                    `${repository}/.github/workflows/ci.yml@${ref}`)), 'exact protected deployment workflow/source required');
+    const run = environment.GITHUB_RUN_ID ?? '';
+    const attempt = environment.GITHUB_RUN_ATTEMPT ?? '';
+    check(/^[1-9]\d*$/.test(run) &&
+        /^[1-9]\d*$/.test(attempt) &&
+        /^(?:[a-f0-9]{40}|[a-f0-9]{64})$/.test(input.source), 'invalid protected invocation identity');
+    const store = await (dependencies.open ?? private_smoke_control_plane_js_1.openPrivateSmokeControlPlane)({
+        account: input.account,
+        stage: input.stage,
+        workspace: input.workspace,
+        policyDigest: (0, router_waf_js_1.routerWafPolicyDigest)(policy),
+    }, cleanupOnly ? undefined : input.url);
+    await (0, private_smoke_admission_js_1.recoverSmokeAdmission)(store, baseline, async (lease) => {
+        // A local process lease has no GitHub run authority; never infer one.
+        if (lease.authority === 'local')
+            return false;
+        // An old attempt of this run can be recovered only after GitHub confirms it ended.
+        if (lease.run === run && lease.attempt === attempt)
+            return cleanupOnly && lease.source === input.source;
+        const token = environment.GITHUB_TOKEN;
+        check(token, 'stale admission requires actions:read to confirm the exact prior run completed');
+        const response = await request(`https://api.github.com/repos/${repository}/actions/runs/${lease.run}/attempts/${lease.attempt}`, {
+            headers: {
+                Authorization: `Bearer ${token}`,
+                Accept: 'application/vnd.github+json',
+            },
+            redirect: 'error',
+            signal: AbortSignal.timeout(15_000),
+        });
+        check(response.ok, 'prior workflow status unavailable; admission retained for protected recovery');
+        const prior = (await response.json());
+        const headRepository = prior.head_repository;
+        return (String(prior.id) === lease.run &&
+            String(prior.run_attempt) === lease.attempt &&
+            prior.status === 'completed' &&
+            prior.head_sha === lease.source &&
+            prior.head_branch === ref.slice('refs/heads/'.length) &&
+            headRepository?.full_name === repository &&
+            ((prior.path === '.github/workflows/deploy.yml' &&
+                prior.event === 'workflow_dispatch') ||
+                (input.deploymentProfile !== 'starter' &&
+                    prior.path === '.github/workflows/ci.yml' &&
+                    prior.event === 'push')));
+    });
+    if (cleanupOnly)
+        return;
+    const ipResponse = await request('https://checkip.amazonaws.com', {
+        redirect: 'error',
+        signal: AbortSignal.timeout(15_000),
+    });
+    check(ipResponse.ok, 'runner IPv4 lookup failed');
+    const address = await ipResponse.text();
+    check(address.length <= 64, 'runner IPv4 response exceeds bound');
+    const cidr = (0, private_smoke_admission_js_1.publicRunnerIpv4)(address.trim());
+    if ((0, private_smoke_admission_js_1.runnerAlreadyAllowed)(cidr, allowedCidrs)) {
+        await input.run();
+        return;
+    }
+    const wait = dependencies.wait ??
+        ((milliseconds) => new Promise((resolve) => setTimeout(resolve, milliseconds)));
+    async function observe(allowed) {
+        for (let poll = 0; poll < 24; poll += 1) {
+            const response = await request(input.url, {
+                redirect: 'manual',
+                signal: AbortSignal.timeout(15_000),
+            });
+            // Do not consume or retain an application response body.
+            await response.body?.cancel();
+            if (allowed
+                ? response.status >= 200 && response.status < 400
+                : response.status === 403)
+                return;
+            if (poll < 23)
+                await wait(5_000);
+        }
+        throw new Error(`Private smoke access: ${allowed ? 'admission' : 'revocation'} was not observed; deployment acceptance prohibited`);
+    }
+    await (0, private_smoke_admission_js_1.withPrivateSmokeAdmission)({
+        store,
+        context: { run, attempt, source: input.source, baseline },
+        cidr,
+        run: input.run,
+        awaitAdmission: () => observe(true),
+        awaitRevocation: () => observe(false),
+    });
+}
+//# sourceMappingURL=private-smoke-access.js.map

package/src/foundation/private-smoke-admission.d.ts

@@ -0,0 +1,45 @@
+export interface SmokeAdmissionContext {
+    authority?: 'local';
+    run: string;
+    attempt: string;
+    source: string;
+    baseline: readonly string[];
+}
+export interface SmokeIpSet {
+    addresses: readonly string[];
+    description: string;
+    lockToken: string;
+}
+export interface SmokeIpSetStore {
+    read(): Promise<SmokeIpSet>;
+    update(previous: SmokeIpSet, next: Pick<SmokeIpSet, 'addresses' | 'description'>): Promise<void>;
+}
+export interface SmokeAdmissionLease {
+    authority?: 'local';
+    run: string;
+    attempt: string;
+    source: string;
+    cidr: string;
+    baseline: string;
+    expiresAt: number;
+}
+export declare function runnerAlreadyAllowed(cidr: string, baseline: readonly string[]): boolean;
+export declare function publicRunnerIpv4(value: string): string;
+export declare function parseSmokeAdmissionLease(description: string): SmokeAdmissionLease | undefined;
+/** Remove only this lease's address. Never replace unrelated addresses with a baseline. */
+export declare function cleanupSmokeAdmission(store: SmokeIpSetStore, context: SmokeAdmissionContext): Promise<void>;
+/** A retained lease alone, or its expiry, is not proof that a different run ended. */
+export declare function recoverSmokeAdmission(store: SmokeIpSetStore, baseline: readonly string[], completedRun: (lease: SmokeAdmissionLease) => Promise<boolean>): Promise<void>;
+export declare function withPrivateSmokeAdmission<T>(input: {
+    store: SmokeIpSetStore;
+    context: SmokeAdmissionContext;
+    cidr: string;
+    run: (lease: SmokeAdmissionLease) => Promise<T>;
+    awaitAdmission: (signal: AbortSignal) => Promise<void>;
+    awaitRevocation: () => Promise<void>;
+    now?: () => number;
+    signals?: {
+        on(event: 'SIGINT' | 'SIGTERM', listener: () => void): unknown;
+        removeListener(event: 'SIGINT' | 'SIGTERM', listener: () => void): unknown;
+    };
+}): Promise<T>;