@sequenceholdings/artifact-studio 0.6.4 → 0.6.6

package/dist/gateway/ingress-snapshot.js

@@ -0,0 +1,63 @@
+/**
+ * The gateway's local copy of every enabled ingress host (design §(e) "Host snapshot"). It is
+ * pulled from `control/ingress-snapshot` on a timer and never on request, so a request for a
+ * random hostname costs a map lookup and can never amplify into an Atlas call.
+ */
+export const INGRESS_SNAPSHOT_INTERVAL_MS = 15_000;
+/** Older than this (Atlas unreachable for eight pulls), every ingress request answers 503. */
+export const INGRESS_SNAPSHOT_STALE_AFTER_MS = 120_000;
+export class IngressSnapshotCache {
+    options;
+    hosts = new Map();
+    snapshot;
+    loadedAt;
+    pending;
+    timer;
+    intervalMs;
+    staleAfterMs;
+    now;
+    constructor(options) {
+        this.options = options;
+        this.intervalMs = options.intervalMs ?? INGRESS_SNAPSHOT_INTERVAL_MS;
+        this.staleAfterMs = options.staleAfterMs ?? INGRESS_SNAPSHOT_STALE_AFTER_MS;
+        this.now = options.now ?? Date.now;
+    }
+    /** Pulls now and then every interval; the timer never keeps the process alive. */
+    start() {
+        if (this.timer)
+            return;
+        void this.refresh();
+        this.timer = setInterval(() => { void this.refresh(); }, this.intervalMs);
+        this.timer.unref();
+    }
+    stop() {
+        clearInterval(this.timer);
+        this.timer = undefined;
+    }
+    /** Single-flight: concurrent callers share one pull. Never rejects. */
+    refresh() {
+        this.pending ??= this.options.load().then((snapshot) => {
+            this.snapshot = snapshot;
+            this.hosts = new Map(snapshot.hosts.map((entry) => [entry.host, entry]));
+            this.loadedAt = this.now();
+        }, () => {
+            this.options.onError?.({ kind: 'ingress_snapshot_failed' });
+        }).finally(() => { this.pending = undefined; });
+        return this.pending;
+    }
+    /** `host` must already be the canonical raw Host. A local map lookup; never a network call. */
+    lookup(host) {
+        const entry = this.hosts.get(host);
+        if (this.loadedAt === undefined || this.now() - this.loadedAt > this.staleAfterMs)
+            return { state: 'stale', entry };
+        return entry ? { state: 'fresh', entry } : { state: 'unknown' };
+    }
+    /** The non-secret per-provider summary the exchange precheck reads; undefined until a pull succeeds. */
+    get providers() {
+        return this.snapshot?.providers;
+    }
+    /** The last pulled snapshot's policy epoch; a newer one on a grant asks for a pull now. */
+    get policyEpoch() {
+        return this.snapshot?.policyEpoch;
+    }
+}

package/dist/gateway/ingress-stages.d.ts

@@ -0,0 +1,60 @@
+import type { IngressSnapshot } from '../server/ingress-control-contract.js';
+import { type ArtifactRequestAdmission } from './admission.js';
+import { type ArtifactGatewayControl } from './control.js';
+import { type IngressAdmission } from './ingress-admission.js';
+import { type IngressPassKeyring } from './ingress-pass.js';
+import type { IngressSnapshotCache } from './ingress-snapshot.js';
+import { type IngressHandlers } from './ingress.js';
+/**
+ * The authenticated half of the external ingress (design "First call" steps 3-5, "Steady state"
+ * steps 4-8, §(d), §(e) "Rate limiting and admission"): pass exchange, logout, and for API routes
+ * local pass verification, admission, grant, freshness, concurrency and the signed v2 context.
+ * Order matters: nothing a forged credential presents reaches Redis or Atlas, and garbage is only
+ * ever counted, never audited (design §(g) "Gateway denials").
+ */
+/** Exchange request bodies above this are refused unread past the limit, before admission. */
+export declare const INGRESS_EXCHANGE_MAX_BODY_BYTES = 1024;
+/** Routes with a body cap at or below this have the body buffered before a concurrency permit. */
+export declare const INGRESS_BUFFERED_BODY_MAX_BYTES: number;
+export interface IngressStagesOptions {
+    control: Pick<ArtifactGatewayControl, 'ingressExchange' | 'ingressGrant' | 'ingressRevoke'>;
+    snapshot: Pick<IngressSnapshotCache, 'providers' | 'policyEpoch' | 'refresh'>;
+    keyring: IngressPassKeyring;
+    /** The gateway's external context key; never the browser one. */
+    externalContext: {
+        privateKey: string;
+        keyId: string;
+    };
+    /** Hosted request concurrency (ACQUIRE-v2). */
+    admission: Pick<ArtifactRequestAdmission, 'acquire'>;
+    ingressAdmission: Pick<IngressAdmission, 'preflight' | 'exchange' | 'logout' | 'request' | 'withPool'>;
+    /** The gateway's APP_ENV: stamped into every pass and required of every pass it verifies. */
+    appEnv: string;
+    /** Epoch milliseconds. */
+    now?: () => number;
+    /** Reuse of a read grant (default 5 s, the authorization cache TTL). */
+    grantCacheTtlMs?: number;
+}
+export declare function subjectHashOf(subject: string): string;
+/**
+ * The structural precheck before any Redis or Atlas call (design "First call" step 3): three
+ * base64url segments, an `alg` among the provider's, a `kid`, and the provider's `iss`. No crypto
+ * and no JWKS: Atlas verifies the token. Returns the token's `exp`, which Atlas verified with it.
+ */
+export declare function precheckIdentityToken({ token, provider }: {
+    token: string;
+    provider: IngressSnapshot['providers'][string];
+}): {
+    exp: number | null;
+} | null;
+export declare function createIngressStages(options: IngressStagesOptions): Required<Pick<IngressHandlers, 'preflight' | 'exchange' | 'logout' | 'admit'>>;
+/**
+ * The usage actor: the context's `ext|<provider>|<subject>` when Atlas's actor grammar accepts it
+ * (no whitespace or control characters, ≤ 255), else the subject's hash, so one odd subject can
+ * never fail a whole usage batch.
+ */
+export declare function usageActor({ provider, subject, subjectHash }: {
+    provider: string;
+    subject: string;
+    subjectHash: string;
+}): string;

package/dist/gateway/ingress-stages.js

@@ -0,0 +1,387 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { z } from 'zod';
+import { artifactNextIngressIdSchema } from '../manifest-next-ingress.js';
+import { INGRESS_ROUTE_METHODS } from '../server/ingress-routes.js';
+import { ArtifactAdmissionError } from './admission.js';
+import { PositiveDecisionCache } from './authorization-cache.js';
+import { IngressControlError } from './control.js';
+import { ingressClientBucket } from './ingress-admission.js';
+import { externalSubject, observeUserAgent, signExternalGatewayContext } from './ingress-context.js';
+import { IngressPassTooLargeError, mintPass, verifyPass } from './ingress-pass.js';
+import { INGRESS_RESPONSE_SECURITY_HEADERS } from './ingress-response.js';
+import { ingressCorsHeaders, IngressError, } from './ingress.js';
+/**
+ * The authenticated half of the external ingress (design "First call" steps 3-5, "Steady state"
+ * steps 4-8, §(d), §(e) "Rate limiting and admission"): pass exchange, logout, and for API routes
+ * local pass verification, admission, grant, freshness, concurrency and the signed v2 context.
+ * Order matters: nothing a forged credential presents reaches Redis or Atlas, and garbage is only
+ * ever counted, never audited (design §(g) "Gateway denials").
+ */
+/** Exchange request bodies above this are refused unread past the limit, before admission. */
+export const INGRESS_EXCHANGE_MAX_BODY_BYTES = 1024;
+/** Routes with a body cap at or below this have the body buffered before a concurrency permit. */
+export const INGRESS_BUFFERED_BODY_MAX_BYTES = 1024 * 1024;
+/** A grant-triggered snapshot pull happens at most this often. */
+const POLICY_REFRESH_MIN_INTERVAL_MS = 1_000;
+/** Only GET reads reuse a grant; HEAD never matches a declared route (INGRESS_ROUTE_METHODS). */
+const READ_METHODS = new Set(['GET']);
+/** Pass refusals whose MAC held: an authentic pass refused by a decision, audited. The rest is garbage. */
+const AUTHENTIC_PASS_REFUSALS = new Set(['expired', 'not_yet_valid', 'wrong_origin', 'wrong_environment']);
+const exchangeBodySchema = z.strictObject({ ingress: artifactNextIngressIdSchema });
+export function subjectHashOf(subject) {
+    return createHash('sha256').update(subject).digest('hex');
+}
+/**
+ * A refused pass (design "Steady state" step 4): always counted; audited only when its MAC held,
+ * so a forged pass costs a local HMAC and a counter increment, never an Atlas audit write.
+ */
+function passRefused({ reason, authentic, detail = {} }) {
+    return new IngressError(401, 'invalid_token', { metric: 'ingress_pass_rejected', ...(authentic ? { audit: { reason, ...detail } } : {}) });
+}
+/** An identity token refused by the structural precheck: garbage, counted and never audited. */
+function tokenRefused() {
+    return new IngressError(401, 'invalid_token', { metric: 'ingress_token_rejected' });
+}
+/** The single `Authorization: Bearer <credential>` value, or null. The handler already refused repeats and oversize. */
+function bearer(request) {
+    const value = request.headers.authorization;
+    const match = typeof value === 'string' ? /^Bearer ([A-Za-z0-9._~+/=-]+)$/i.exec(value) : null;
+    return match ? match[1] : null;
+}
+function decodeJsonSegment(segment) {
+    try {
+        return JSON.parse(Buffer.from(segment, 'base64url').toString('utf8'));
+    }
+    catch {
+        return undefined;
+    }
+}
+const jwsHeaderSchema = z.object({ alg: z.string(), kid: z.string().min(1).max(256) });
+const jwsPayloadSchema = z.object({ iss: z.string(), exp: z.number().int().positive().optional() });
+/**
+ * The structural precheck before any Redis or Atlas call (design "First call" step 3): three
+ * base64url segments, an `alg` among the provider's, a `kid`, and the provider's `iss`. No crypto
+ * and no JWKS: Atlas verifies the token. Returns the token's `exp`, which Atlas verified with it.
+ */
+export function precheckIdentityToken({ token, provider }) {
+    const parts = token.split('.');
+    if (parts.length !== 3 || !parts.every((part) => /^[A-Za-z0-9_-]+$/.test(part)))
+        return null;
+    const header = jwsHeaderSchema.safeParse(decodeJsonSegment(parts[0]));
+    const payload = jwsPayloadSchema.safeParse(decodeJsonSegment(parts[1]));
+    if (!header.success || !payload.success)
+        return null;
+    if (!provider.algorithms.includes(header.data.alg) || payload.data.iss !== provider.issuer)
+        return null;
+    return { exp: payload.data.exp ?? null };
+}
+/** The body, read up to `maxBytes`; beyond it 413 with nothing more read. */
+async function readBounded({ request, maxBytes }) {
+    const declared = Number(request.headers['content-length']);
+    if (Number.isFinite(declared) && declared > maxBytes)
+        throw new IngressError(413, 'payload_too_large');
+    const chunks = [];
+    let length = 0;
+    for await (const chunk of request) {
+        const bytes = Buffer.from(chunk);
+        length += bytes.length;
+        if (length > maxBytes)
+            throw new IngressError(413, 'payload_too_large');
+        chunks.push(bytes);
+    }
+    return Buffer.concat(chunks);
+}
+/** A refusal an Atlas control route returned, as the caller sees it; never audited by the gateway. */
+function fromControl(error) {
+    if (error instanceof IngressControlError && error.code !== null) {
+        return new IngressError(error.status, error.code, error.retryAfterSeconds === undefined ? {} : { retryAfterSeconds: error.retryAfterSeconds });
+    }
+    if (error instanceof ArtifactAdmissionError)
+        return fromAdmission(error);
+    // A bare failure, a timeout or an unparseable answer: an outage the caller may retry.
+    return new IngressError(503, 'temporarily_unavailable', error instanceof IngressControlError && error.retryAfterSeconds !== undefined ? { retryAfterSeconds: error.retryAfterSeconds } : {});
+}
+/** A rate limit or a Redis outage: a metric, never an audit event (a flood or an outage would become one per request). */
+function fromAdmission(error) {
+    return error.status === 429
+        ? new IngressError(429, 'rate_limited', { retryAfterSeconds: error.retryAfterSeconds ?? 1, metric: 'admission_rejected' })
+        : new IngressError(503, 'temporarily_unavailable', { retryAfterSeconds: error.retryAfterSeconds ?? 2, metric: 'admission_rejected' });
+}
+async function admitted(work) {
+    try {
+        return await work();
+    }
+    catch (error) {
+        if (error instanceof ArtifactAdmissionError)
+            throw fromAdmission(error);
+        throw error;
+    }
+}
+/** A buffered body as the stream the proxy forwards. */
+async function* replay(body) {
+    if (body.length > 0)
+        yield body;
+}
+function writeJson({ response, status, body, corsOrigin }) {
+    response.writeHead(status, {
+        ...INGRESS_RESPONSE_SECURITY_HEADERS,
+        ...(body === undefined ? {} : { 'content-type': 'application/json' }),
+        ...(corsOrigin ? ingressCorsHeaders(corsOrigin) : {}),
+    });
+    response.end(body === undefined ? undefined : JSON.stringify(body));
+}
+/** The caller's origin for CORS on a success, or a 403 when this ingress does not allow it. */
+function ingressOrigin({ origin, ingress }) {
+    if (origin === null)
+        return null;
+    if (!ingress.allowedOrigins.includes(origin))
+        throw new IngressError(403, 'forbidden', { audit: { reason: 'origin_not_allowed', ingress: ingress.id } });
+    return origin;
+}
+function grantCacheKey(parts) {
+    return createHash('sha256').update(JSON.stringify(['ingress-grant-v1', ...parts])).digest('hex');
+}
+export function createIngressStages(options) {
+    const now = options.now ?? Date.now;
+    const seconds = () => Math.floor(now() / 1000);
+    const grants = new PositiveDecisionCache({ ttlMs: options.grantCacheTtlMs, now });
+    let lastPolicyRefresh = Number.NEGATIVE_INFINITY;
+    /** Local pass verification (design "Steady state" step 4): no Redis, no Atlas; failure is 401, uncharged. */
+    function verifiedPass({ request, publicOrigin, entry }) {
+        const token = bearer(request);
+        if (!token)
+            throw passRefused({ reason: 'pass_missing', authentic: false });
+        const verification = verifyPass({ keyring: options.keyring, token, now: seconds(), origin: publicOrigin, env: options.appEnv });
+        if (!verification.ok)
+            throw passRefused({ reason: `pass_${verification.reason}`, authentic: AUTHENTIC_PASS_REFUSALS.has(verification.reason) });
+        const { payload } = verification;
+        const ingress = entry.ingresses.find((candidate) => candidate.id === payload.ingress && candidate.provider === payload.provider);
+        if (!ingress || payload.projectId !== entry.projectId)
+            throw passRefused({ reason: 'pass_wrong_ingress', authentic: true, detail: { passId: payload.jti } });
+        return { pass: payload, kid: verification.kid, ingress };
+    }
+    async function preflight({ clientIp }) {
+        await admitted(() => options.ingressAdmission.preflight({ clientIp }));
+    }
+    async function exchange(input) {
+        const { request, response, host, publicOrigin, entry, clientIp, origin, requestId } = input;
+        // Read, bounded, before admission (design §(e) "Limits").
+        if (request.headers['content-type']?.split(';', 1)[0]?.trim().toLowerCase() !== 'application/json')
+            throw new IngressError(400, 'bad_request');
+        const raw = await readBounded({ request, maxBytes: INGRESS_EXCHANGE_MAX_BODY_BYTES });
+        let parsedBody;
+        try {
+            parsedBody = JSON.parse(raw.toString('utf8'));
+        }
+        catch {
+            throw new IngressError(400, 'bad_request');
+        }
+        const body = exchangeBodySchema.safeParse(parsedBody);
+        if (!body.success)
+            throw new IngressError(400, 'bad_request');
+        const ingress = entry.ingresses.find((candidate) => candidate.id === body.data.ingress);
+        if (!ingress)
+            throw new IngressError(404, 'not_found');
+        const corsOrigin = ingressOrigin({ origin, ingress });
+        const token = bearer(request);
+        if (!token)
+            throw tokenRefused();
+        const provider = options.snapshot.providers?.[ingress.provider];
+        if (!provider)
+            throw new IngressError(503, 'temporarily_unavailable');
+        const precheck = precheckIdentityToken({ token, provider });
+        if (!precheck)
+            throw tokenRefused();
+        const release = await admitted(() => options.ingressAdmission.exchange({ clientIp, host }));
+        let verified;
+        try {
+            verified = await options.control.ingressExchange({
+                host, ingress: ingress.id, origin, token, clientIp, userAgent: observeUserAgent(request.headers['user-agent']).userAgent, requestId,
+            });
+        }
+        catch (error) {
+            throw fromControl(error);
+        }
+        finally {
+            release();
+        }
+        const { principal } = verified;
+        // The context's `sub` is `ext|<provider>|<subject>`, at most 255 characters (design §(f)).
+        const denied = (reason) => new IngressError(403, 'exchange_denied', { audit: { reason, ingress: ingress.id, subjectHash: subjectHashOf(principal.subject) } });
+        if (externalSubject({ provider: ingress.provider, subject: principal.subject }).length > 255)
+            throw denied('subject_too_long');
+        const iat = seconds();
+        const exp = Math.min(precheck.exp ?? Number.POSITIVE_INFINITY, iat + verified.passTtlSeconds);
+        if (exp <= iat)
+            throw new IngressError(401, 'invalid_token', { audit: { reason: 'token_expired', ingress: ingress.id } });
+        let pass;
+        try {
+            pass = mintPass({ keyring: options.keyring, payload: {
+                    v: 1, typ: 'artifact-ingress-pass', env: options.appEnv, origin: publicOrigin, projectId: entry.projectId,
+                    ingress: ingress.id, provider: ingress.provider, bep: verified.bindingEpoch, ...principal,
+                    exchangeIp: clientIp, jti: randomUUID(), iat, exp,
+                } });
+        }
+        catch (error) {
+            // A principal near the schema maxima never fits: a decided refusal, not an outage to retry.
+            if (error instanceof IngressPassTooLargeError)
+                throw denied('pass_too_large');
+            throw error;
+        }
+        // `expiresAt` is epoch milliseconds, as the BAP's other token clocks are.
+        writeJson({ response, status: 200, body: { token: pass, expiresAt: exp * 1000 }, corsOrigin });
+    }
+    async function logout(input) {
+        const { response, host, clientIp, origin } = input;
+        const { pass, ingress } = verifiedPass(input);
+        const corsOrigin = ingressOrigin({ origin, ingress });
+        const subjectHash = subjectHashOf(pass.subject);
+        const release = await admitted(() => options.ingressAdmission.logout({ provider: pass.provider, subjectHash, clientIp }));
+        try {
+            await options.control.ingressRevoke({ host, ingress: ingress.id, provider: pass.provider, subject: pass.subject, passJti: pass.jti, tokenIssuedAt: pass.tokenIssuedAt });
+        }
+        catch (error) {
+            throw fromControl(error);
+        }
+        finally {
+            release();
+        }
+        writeJson({ response, status: 204, corsOrigin });
+    }
+    /** A grant for this exact (route, method), cached ≤ 5 s for reads only, under an `ingress-grant` permit. */
+    async function grantFor({ input, pass, subjectHash }) {
+        const method = input.request.method ?? 'GET';
+        const body = {
+            host: input.host, ingress: input.ingress.id, provider: input.ingress.provider, subjectHash, tokenIssuedAt: pass.tokenIssuedAt,
+            passJti: pass.jti, method: z.enum(INGRESS_ROUTE_METHODS).parse(method), routeId: input.match.routeId,
+        };
+        // The snapshot's target is part of the key: after an `artifact dev` restart a refreshed
+        // snapshot names the new session, so a read grant cached for the old one must miss.
+        const { target } = input.entry;
+        const lookup = {
+            key: grantCacheKey([body.host, body.ingress, subjectHash, body.passJti, body.routeId, body.method, target.kind === 'development' ? `development:${target.sessionId}` : 'published']),
+            load: () => options.ingressAdmission.withPool('ingress-grant', () => options.control.ingressGrant(body)),
+            notAfter: (grant) => grant.expiresAt,
+        };
+        try {
+            // Mutations always ask Atlas: revocation, a disabled binding or a new release stop them at once.
+            return READ_METHODS.has(method) ? await grants.get(lookup) : await grants.refresh(lookup);
+        }
+        catch (error) {
+            throw fromControl(error);
+        }
+    }
+    /** Pulls the snapshot now, at most once a second. A cache-buster only, never a reason to deny. */
+    function refreshSnapshot() {
+        if (now() - lastPolicyRefresh < POLICY_REFRESH_MIN_INTERVAL_MS)
+            return;
+        lastPolicyRefresh = now();
+        void options.snapshot.refresh();
+    }
+    /**
+     * The grant's release, or 503 when it does not match the snapshot entry it was asked for: a
+     * published grant only for a published target, and a development grant only on a development
+     * gateway (its own APP_ENV, never a value from the request or Atlas), for the snapshot's own
+     * development session (design §(j.3) steps 3-4). Never proxied over either session id alone:
+     * after an `artifact dev` restart inside one poll the two differ, so the request is refused and
+     * the snapshot pulled at once.
+     */
+    function releaseOf({ grant, entry }) {
+        const unavailable = () => { refreshSnapshot(); return new IngressError(503, 'temporarily_unavailable'); };
+        if (grant.mode === 'published') {
+            if (entry.target.kind !== 'published')
+                throw unavailable();
+            return { mode: 'published', deploymentId: grant.deploymentId };
+        }
+        if (options.appEnv !== 'development')
+            throw new IngressError(503, 'temporarily_unavailable');
+        if (entry.target.kind !== 'development' || entry.target.sessionId !== grant.devSessionId)
+            throw unavailable();
+        return { mode: 'development', devSessionId: grant.devSessionId };
+    }
+    /** Route freshness (design §(h)): `fresh_auth_seconds` against the pass's sign-in time, else a step-up 401. */
+    function requireFreshAuth({ pass, freshness, detail }) {
+        if (freshness > 0 && (pass.authTime === null || seconds() - pass.authTime > freshness)) {
+            throw new IngressError(401, 'insufficient_user_authentication', {
+                wwwAuthenticate: `Bearer error="insufficient_user_authentication", max_age=${freshness}`,
+                audit: { reason: 'step_up_required', ...detail },
+            });
+        }
+    }
+    /** A grant for this request that a context may still be signed with, and its release, else 503 before signing. */
+    async function usableGrant({ input, pass, detail }) {
+        const grant = await grantFor({ input, pass, subjectHash: detail.subjectHash });
+        if (grant.projectId !== input.entry.projectId || grant.expiresAt <= now())
+            throw new IngressError(503, 'temporarily_unavailable');
+        if (grant.policyEpoch > (options.snapshot.policyEpoch ?? 0))
+            refreshSnapshot();
+        const release = releaseOf({ grant, entry: input.entry });
+        // A deployment that does not trust the gateway's current kid would refuse the context: 503 before signing.
+        if (!grant.trustedExternalKids.includes(options.externalContext.keyId))
+            throw new IngressError(503, 'temporarily_unavailable', { audit: { reason: 'untrusted_external_kid', ...detail } });
+        return { grant, release };
+    }
+    async function admit(input) {
+        const { request, entry, ingress, match, clientIp, origin, requestId, signedPath } = input;
+        const { pass, kid: passKid, ingress: passIngress } = verifiedPass(input);
+        // A pass is good for its own ingress's routes only, whatever other ingress the host carries.
+        if (passIngress.id !== ingress.id)
+            throw passRefused({ reason: 'pass_wrong_ingress', authentic: true, detail: { ingress: ingress.id, passId: pass.jti } });
+        const subjectHash = subjectHashOf(pass.subject);
+        const detail = { ingress: ingress.id, subjectHash, passId: pass.jti };
+        const freshness = match.route.fresh_auth_seconds ?? 0;
+        // Freshness needs only the verified pass: refused early, before any Redis count or Atlas grant.
+        requireFreshAuth({ pass, freshness, detail });
+        await admitted(() => options.ingressAdmission.request({ provider: pass.provider, subjectHash, projectId: entry.projectId, ingressId: ingress.id }));
+        let { grant, release } = await usableGrant({ input, pass, detail });
+        const maxBodyBytes = match.route.max_body_bytes;
+        let body;
+        if (maxBodyBytes <= INGRESS_BUFFERED_BODY_MAX_BYTES) {
+            body = replay(await readBounded({ request, maxBytes: maxBodyBytes }));
+            // A slow upload can outlive the pass, the route's freshness window and the grant: decide all
+            // three again before signing, so nothing is forwarded on an authorization that has lapsed.
+            if (pass.exp <= seconds())
+                throw passRefused({ reason: 'pass_expired', authentic: true, detail: { ingress: ingress.id, passId: pass.jti } });
+            requireFreshAuth({ pass, freshness, detail });
+            if (grant.expiresAt <= now())
+                ({ grant, release } = await usableGrant({ input, pass, detail }));
+        }
+        // A development session takes the deployment's place in the concurrency keys.
+        const releaseId = release.mode === 'published' ? release.deploymentId : release.devSessionId;
+        const lease = await admitted(() => options.admission.acquire({ environment: grant.environment, projectId: grant.projectId, deploymentId: releaseId, resources: grant.resources }, { ingress: { id: ingress.id, subjectHash, clientBucket: ingressClientBucket(clientIp) } }));
+        let requestContext;
+        try {
+            requestContext = signExternalGatewayContext({
+                privateKey: options.externalContext.privateKey, keyId: options.externalContext.keyId,
+                projectId: grant.projectId, environment: grant.environment, release, requestId,
+                method: request.method ?? 'GET', path: signedPath, serviceAccountId: grant.serviceAccountId, pass, passKid,
+                client: { ip: clientIp, ...observeUserAgent(request.headers['user-agent']), origin }, now: seconds(),
+            });
+        }
+        catch (error) {
+            void lease.release().catch(() => undefined);
+            throw error;
+        }
+        const attribution = { actorId: usageActor({ provider: pass.provider, subject: pass.subject, subjectHash }), ingressId: ingress.id, projectId: grant.projectId, environment: grant.environment };
+        return {
+            target: grant.mode === 'published'
+                ? { upstreamUrl: grant.upstreamUrl, upstreamAudience: grant.upstreamAudience, projectId: grant.projectId, deploymentId: grant.deploymentId }
+                : { kind: 'development', projectId: grant.projectId, environment: grant.environment, sessionId: grant.devSessionId },
+            requestContext,
+            timeoutMs: lease.timeoutMs,
+            bind: (response, abort) => { lease.bind(response, abort); },
+            ...(body ? { body } : {}),
+            usage: release.mode === 'published' ? { ...attribution, deploymentId: release.deploymentId } : { ...attribution, devSessionId: release.devSessionId },
+        };
+    }
+    return { preflight, exchange, logout, admit };
+}
+/**
+ * The usage actor: the context's `ext|<provider>|<subject>` when Atlas's actor grammar accepts it
+ * (no whitespace or control characters, ≤ 255), else the subject's hash, so one odd subject can
+ * never fail a whole usage batch.
+ */
+export function usageActor({ provider, subject, subjectHash }) {
+    const actor = externalSubject({ provider, subject });
+    return actor.length <= 255 && /^[^\s\p{Cc}]+$/u.test(actor) ? actor : externalSubject({ provider, subject: `sha256:${subjectHash}` });
+}