@sequenceholdings/artifact-studio 0.6.4 → 0.6.7

package/dist/gateway/ingress-response.js

@@ -0,0 +1,98 @@
+import { isSharedCacheDirective, SHARED_CACHE_REFUSAL } from '../tunnel/protocol.js';
+/**
+ * Response policy for an external ingress (design §(e) "Response policy"). An ingress answers a
+ * cross-origin caller that is not an Atlas user, so nothing it returns may become a document, a
+ * redirect, a stream, a cookie or a cache entry: the only output is data of a type the route
+ * declared. The decision is taken on the status line and headers, before any body byte is sent.
+ */
+/**
+ * Set on every ingress response, the gateway's own errors included. The shared-cache refusal is
+ * the one every protected session response carries, so no zone cache rule can hold borrower data.
+ */
+export const INGRESS_RESPONSE_SECURITY_HEADERS = Object.freeze({
+    'content-security-policy': "default-src 'none'; sandbox; frame-ancestors 'none'",
+    'x-content-type-options': 'nosniff',
+    'referrer-policy': 'no-referrer',
+    'cross-origin-resource-policy': 'same-origin',
+    'cache-control': 'private, no-store',
+    ...SHARED_CACHE_REFUSAL,
+});
+// The app may not set CORS, cookies, framing or navigation; the gateway owns the security headers
+// above and the request id it generated.
+const STRIPPED_RESPONSE_HEADERS = new Set([
+    'set-cookie', 'clear-site-data', 'x-frame-options', 'refresh', 'x-request-id',
+    'content-security-policy-report-only', ...Object.keys(INGRESS_RESPONSE_SECURITY_HEADERS),
+]);
+const JSON_TYPES = new Set(['application/json', 'application/problem+json']);
+function mediaType(value) {
+    if (typeof value !== 'string')
+        return undefined;
+    const type = value.split(';', 1)[0].trim().toLowerCase();
+    return type === '' ? undefined : type;
+}
+function attachment(disposition) {
+    if (typeof disposition !== 'string')
+        return 'attachment';
+    // Keep the app's parameters (filename) and replace only the disposition type.
+    const parameters = disposition.split(';').slice(1).map((part) => part.trim()).filter(Boolean);
+    return ['attachment', ...parameters].join('; ');
+}
+/**
+ * The upstream's declared body length, read from the raw head: the shared sanitising removes
+ * `content-length` as a hop header, so the policy must be handed it explicitly. The same parser
+ * the development tunnel uses, so hosted and development ingress judge a head alike.
+ */
+export { declaredLength as declaredContentLength } from '../tunnel/external.js';
+/**
+ * Decides an upstream response on an ingress route. `headers` are the app's headers after the
+ * shared private-header sanitising (no `content-length`); `declaredLength` is the upstream's own
+ * `Content-Length`; `responses` are the matched route's declared content types.
+ */
+export function applyIngressResponsePolicy({ status, method, headers, declaredLength, responses }) {
+    // 304 carries no body and no destination; every other 3xx would navigate a cross-origin caller.
+    if (status >= 300 && status < 400 && status !== 304)
+        return { allowed: false, reason: 'redirect' };
+    const type = mediaType(headers['content-type']);
+    if (type === 'text/event-stream')
+        return { allowed: false, reason: 'event_stream' };
+    if (type === undefined) {
+        const empty = status === 204 || status === 304 || method === 'HEAD' || declaredLength === 0;
+        if (!empty || headers['content-type'] !== undefined)
+            return { allowed: false, reason: 'missing_content_type' };
+    }
+    else if (type !== 'application/problem+json' && !responses.includes(type)) {
+        return { allowed: false, reason: 'content_type' };
+    }
+    const kept = {};
+    for (const [name, value] of Object.entries(headers)) {
+        if (STRIPPED_RESPONSE_HEADERS.has(name) || name.startsWith('access-control-') || isSharedCacheDirective(name))
+            continue;
+        kept[name] = value;
+    }
+    if (type === undefined || !JSON_TYPES.has(type))
+        kept['content-disposition'] = attachment(headers['content-disposition']);
+    return { allowed: true, headers: { ...kept, ...INGRESS_RESPONSE_SECURITY_HEADERS } };
+}
+/**
+ * Applies the policy to an upstream head and writes the allowed status and headers onto the
+ * gateway response. False when the response is refused (502 before any body byte), including a
+ * declared length above the ingress response cap.
+ */
+export function writeIngressResponseHead({ response, status, method, headers, declaredLength, responses, maxResponseBytes }) {
+    const decision = applyIngressResponsePolicy({ status, method, headers, declaredLength, responses });
+    if (!decision.allowed || (declaredLength !== null && declaredLength > maxResponseBytes))
+        return false;
+    response.statusCode = status;
+    for (const [name, value] of Object.entries(decision.headers)) {
+        // The gateway's `Vary: Origin` (set with CORS) survives an app's own Vary.
+        const vary = name === 'vary' ? response.getHeader('vary') : undefined;
+        response.setHeader(name, typeof vary === 'string' ? `${vary}, ${Array.isArray(value) ? value.join(', ') : value}` : value);
+    }
+    return true;
+}
+/** An ingress caller gets a deterministic 504 before its 60 s context expires (design §(e) "Limits"). */
+export const INGRESS_PROXY_LIMITS = Object.freeze({ maxTimeoutMs: 55_000, idleWriteTimeoutMs: 10_000 });
+/** Error contract codes (design §(i)) for the failures the proxy itself decides. */
+export const INGRESS_PROXY_ERROR_CODES = Object.freeze({
+    400: 'bad_request', 413: 'payload_too_large', 502: 'upstream_response_refused', 503: 'temporarily_unavailable', 504: 'upstream_timeout',
+});

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

@@ -0,0 +1,86 @@
+import { z } from 'zod';
+import type { AdmissionRedis, ArtifactRequestAdmission } from './admission.js';
+import type { ArtifactGatewayControl } from './control.js';
+import { type IngressAuditFailure } from './ingress-audit.js';
+import { type IngressPassKeyring } from './ingress-pass.js';
+import { type ArtifactGatewayIngressOptions } from './ingress.js';
+/**
+ * Startup of the external ingress branch (design §(b.1) item 4): its four secrets, the checks
+ * that keep them independent of every other gateway secret, and the wiring of snapshot,
+ * admission, stages and denial audit. Errors and logs name variables, never values.
+ */
+export declare const INGRESS_SECRET_NAMES: readonly ["ARTIFACT_NEXT_EXTERNAL_CONTEXT_PRIVATE_KEY", "ARTIFACT_NEXT_EXTERNAL_CONTEXT_KEY_ID", "ARTIFACT_NEXT_INGRESS_PASS_KEYS", "ARTIFACT_NEXT_INGRESS_EDGE_SECRETS"];
+type IngressSecretName = typeof INGRESS_SECRET_NAMES[number];
+export interface IngressSecrets {
+    externalContext: {
+        privateKey: string;
+        keyId: string;
+    };
+    keyring: IngressPassKeyring;
+    /** Current and, during a rotation, next. */
+    edgeSecrets: string[];
+}
+export type IngressSecretsResult = 
+/** All four absent (`missing` lists all four) or only some present: the branch stays off. */
+{
+    state: 'disabled';
+    missing: IngressSecretName[];
+    partial: boolean;
+} | {
+    state: 'enabled';
+    secrets: IngressSecrets;
+};
+/** A refusal to boot: the ingress secrets are present but unusable. Its message names variables only. */
+export declare class IngressSecretsError extends Error {
+    constructor(message: string);
+}
+/** `ARTIFACT_NEXT_INGRESS_EDGE_SECRETS`: `{"current":"…","next":"…"|null}`, each at least 32 characters. */
+export declare const ingressEdgeSecretsSchema: z.ZodObject<{
+    current: z.ZodString;
+    next: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+}, z.core.$strict>;
+/**
+ * Reads the four ingress secrets. All absent: disabled (the image can roll before the secrets
+ * exist). Some absent: disabled, with `partial` so the caller logs an error naming them. All
+ * present: enabled, or IngressSecretsError when any is malformed, when any two of {control token,
+ * session key, each pass key, each edge secret} are equal, when the external context key is the
+ * browser context key, or when the browser key id is the external one or an `external-` id (the
+ * sidecar pairs `external-` kids with v2 contexts only).
+ */
+export declare function loadIngressSecrets({ env, controlToken, sessionKey, browserContextPrivateKey, browserContextKeyId }: {
+    env: Readonly<Record<string, string | undefined>>;
+    controlToken: string;
+    sessionKey: string;
+    browserContextPrivateKey: string;
+    browserContextKeyId: string;
+}): IngressSecretsResult;
+export interface IngressRuntime {
+    /** Absent: the branch is disabled and every ingress host answers 404. */
+    ingress: ArtifactGatewayIngressOptions | undefined;
+    /** Starts the snapshot pulls and the denial audit flushes. */
+    start(): void;
+    /** Stops them and delivers the buffered refusals. */
+    close(): Promise<void>;
+}
+/**
+ * The ingress branch for one gateway process, or none. Throws IngressSecretsError (the process
+ * must refuse to boot) only when every secret is present and one is unusable.
+ */
+export declare function createIngressRuntime({ env, control, controlToken, sessionKey, contextPrivateKey, contextKeyId, redis, namespace, admission, log, onFailure }: {
+    env: Readonly<Record<string, string | undefined>>;
+    control: ArtifactGatewayControl;
+    controlToken: string;
+    sessionKey: string;
+    contextPrivateKey: string;
+    /** ARTIFACT_NEXT_CONTEXT_KEY_ID, the browser context key's id. */
+    contextKeyId: string;
+    redis: AdmissionRedis;
+    /** APP_ENV. */
+    namespace: string;
+    admission: Pick<ArtifactRequestAdmission, 'acquire'>;
+    log: (event: Record<string, unknown>) => void;
+    onFailure?: (failure: IngressAuditFailure | {
+        kind: 'ingress_snapshot_failed';
+    }) => void;
+}): IngressRuntime;
+export {};

package/dist/gateway/ingress-runtime.js

@@ -0,0 +1,126 @@
+import { createHash, createPrivateKey, timingSafeEqual } from 'node:crypto';
+import { z } from 'zod';
+import { ingressExternalKidSchema } from '../server/ingress-control-contract.js';
+import { IngressAdmission } from './ingress-admission.js';
+import { IngressDenialAuditor } from './ingress-audit.js';
+import { ingressPassKeyringSchema } from './ingress-pass.js';
+import { IngressSnapshotCache } from './ingress-snapshot.js';
+import { createIngressStages } from './ingress-stages.js';
+import { MIN_EDGE_SECRET_LENGTH } from './ingress.js';
+/**
+ * Startup of the external ingress branch (design §(b.1) item 4): its four secrets, the checks
+ * that keep them independent of every other gateway secret, and the wiring of snapshot,
+ * admission, stages and denial audit. Errors and logs name variables, never values.
+ */
+export const INGRESS_SECRET_NAMES = [
+    'ARTIFACT_NEXT_EXTERNAL_CONTEXT_PRIVATE_KEY',
+    'ARTIFACT_NEXT_EXTERNAL_CONTEXT_KEY_ID',
+    'ARTIFACT_NEXT_INGRESS_PASS_KEYS',
+    'ARTIFACT_NEXT_INGRESS_EDGE_SECRETS',
+];
+/** A refusal to boot: the ingress secrets are present but unusable. Its message names variables only. */
+export class IngressSecretsError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'IngressSecretsError';
+    }
+}
+/** `ARTIFACT_NEXT_INGRESS_EDGE_SECRETS`: `{"current":"…","next":"…"|null}`, each at least 32 characters. */
+export const ingressEdgeSecretsSchema = z.strictObject({
+    current: z.string().min(MIN_EDGE_SECRET_LENGTH).max(1024),
+    next: z.string().min(MIN_EDGE_SECRET_LENGTH).max(1024).nullable().default(null),
+});
+function parseJson(value) {
+    try {
+        return JSON.parse(value);
+    }
+    catch {
+        return undefined;
+    }
+}
+function digest(value) {
+    return createHash('sha256').update(value).digest();
+}
+/** Every pair compared in constant time, all of them, so timing reveals neither which nor whether. */
+function anyEqual(values) {
+    const digests = values.map(digest);
+    let equal = false;
+    for (let left = 0; left < digests.length; left++) {
+        for (let right = left + 1; right < digests.length; right++)
+            equal = timingSafeEqual(digests[left], digests[right]) || equal;
+    }
+    return equal;
+}
+function privateKeyBytes(pem, name) {
+    let key;
+    try {
+        key = createPrivateKey(pem);
+    }
+    catch {
+        throw new IngressSecretsError(`${name} is not a private key`);
+    }
+    if (key.asymmetricKeyType !== 'ed25519')
+        throw new IngressSecretsError(`${name} must be an Ed25519 key`);
+    return key.export({ format: 'der', type: 'pkcs8' });
+}
+/**
+ * Reads the four ingress secrets. All absent: disabled (the image can roll before the secrets
+ * exist). Some absent: disabled, with `partial` so the caller logs an error naming them. All
+ * present: enabled, or IngressSecretsError when any is malformed, when any two of {control token,
+ * session key, each pass key, each edge secret} are equal, when the external context key is the
+ * browser context key, or when the browser key id is the external one or an `external-` id (the
+ * sidecar pairs `external-` kids with v2 contexts only).
+ */
+export function loadIngressSecrets({ env, controlToken, sessionKey, browserContextPrivateKey, browserContextKeyId }) {
+    const missing = INGRESS_SECRET_NAMES.filter((name) => !env[name]);
+    if (missing.length > 0)
+        return { state: 'disabled', missing, partial: missing.length < INGRESS_SECRET_NAMES.length };
+    const privateKey = env.ARTIFACT_NEXT_EXTERNAL_CONTEXT_PRIVATE_KEY;
+    const keyId = env.ARTIFACT_NEXT_EXTERNAL_CONTEXT_KEY_ID;
+    if (!ingressExternalKidSchema.safeParse(keyId).success)
+        throw new IngressSecretsError('ARTIFACT_NEXT_EXTERNAL_CONTEXT_KEY_ID must start with external-');
+    if (browserContextKeyId === keyId || browserContextKeyId.startsWith('external-')) {
+        throw new IngressSecretsError('ARTIFACT_NEXT_CONTEXT_KEY_ID must differ from ARTIFACT_NEXT_EXTERNAL_CONTEXT_KEY_ID and must not start with external-');
+    }
+    const keyring = ingressPassKeyringSchema.safeParse(parseJson(env.ARTIFACT_NEXT_INGRESS_PASS_KEYS));
+    if (!keyring.success)
+        throw new IngressSecretsError('ARTIFACT_NEXT_INGRESS_PASS_KEYS is malformed');
+    const edge = ingressEdgeSecretsSchema.safeParse(parseJson(env.ARTIFACT_NEXT_INGRESS_EDGE_SECRETS));
+    if (!edge.success)
+        throw new IngressSecretsError('ARTIFACT_NEXT_INGRESS_EDGE_SECRETS is malformed');
+    const external = privateKeyBytes(privateKey, 'ARTIFACT_NEXT_EXTERNAL_CONTEXT_PRIVATE_KEY');
+    const browser = privateKeyBytes(browserContextPrivateKey, 'ARTIFACT_NEXT_CONTEXT_PRIVATE_KEY');
+    const edgeSecrets = [edge.data.current, ...(edge.data.next === null ? [] : [edge.data.next])];
+    const independent = [controlToken, sessionKey, ...Object.values(keyring.data.keys), ...edgeSecrets].map((value) => Buffer.from(value, 'utf8'));
+    if (anyEqual(independent)) {
+        throw new IngressSecretsError('Gateway secrets must be independent: the control token, session key, pass keys and edge secrets must all differ');
+    }
+    if (anyEqual([external, browser]))
+        throw new IngressSecretsError('ARTIFACT_NEXT_EXTERNAL_CONTEXT_PRIVATE_KEY must not be the browser context key');
+    return { state: 'enabled', secrets: { externalContext: { privateKey, keyId }, keyring: keyring.data, edgeSecrets } };
+}
+/**
+ * The ingress branch for one gateway process, or none. Throws IngressSecretsError (the process
+ * must refuse to boot) only when every secret is present and one is unusable.
+ */
+export function createIngressRuntime({ env, control, controlToken, sessionKey, contextPrivateKey, contextKeyId, redis, namespace, admission, log, onFailure }) {
+    const loaded = loadIngressSecrets({ env, controlToken, sessionKey, browserContextPrivateKey: contextPrivateKey, browserContextKeyId: contextKeyId });
+    if (loaded.state === 'disabled') {
+        if (loaded.partial)
+            log({ event: 'artifact_gateway.ingress_disabled', level: 'error', missing: loaded.missing });
+        return { ingress: undefined, start: () => undefined, close: async () => undefined };
+    }
+    log({ event: 'artifact_gateway.ingress_secrets_checked', message: 'ingress secrets checked' });
+    const { secrets } = loaded;
+    const snapshot = new IngressSnapshotCache({ load: () => control.ingressSnapshot(), onError: (event) => onFailure?.(event) });
+    const auditor = new IngressDenialAuditor({ send: (batch) => control.ingressAudit(batch), onFailure });
+    const handlers = createIngressStages({
+        control, snapshot, keyring: secrets.keyring, externalContext: secrets.externalContext, admission,
+        ingressAdmission: new IngressAdmission({ redis, namespace }), appEnv: namespace,
+    });
+    return {
+        ingress: { edgeSecrets: secrets.edgeSecrets, snapshot, appEnv: namespace, handlers, onDenial: (event) => auditor.record(event) },
+        start: () => { snapshot.start(); auditor.start(); },
+        close: async () => { snapshot.stop(); await auditor.close(); },
+    };
+}

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

@@ -0,0 +1,54 @@
+import type { IngressSnapshot, IngressSnapshotHost } from '../server/ingress-control-contract.js';
+/**
+ * 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 declare const INGRESS_SNAPSHOT_INTERVAL_MS = 15000;
+/** Older than this (Atlas unreachable for eight pulls), every ingress request answers 503. */
+export declare const INGRESS_SNAPSHOT_STALE_AFTER_MS = 120000;
+export type IngressSnapshotLookup = {
+    state: 'fresh';
+    entry: IngressSnapshotHost;
+} | {
+    state: 'unknown';
+}
+/** Too old to act on. `entry` is the last known one, for CORS on the 503 only. */
+ | {
+    state: 'stale';
+    entry: IngressSnapshotHost | undefined;
+};
+export interface IngressSnapshotCacheOptions {
+    /** Fetches and validates the snapshot (`ArtifactGatewayControl.ingressSnapshot`). */
+    load: () => Promise<IngressSnapshot>;
+    intervalMs?: number;
+    staleAfterMs?: number;
+    now?: () => number;
+    /** A failed pull keeps the previous snapshot until it goes stale. */
+    onError?: (event: {
+        kind: 'ingress_snapshot_failed';
+    }) => void;
+}
+export declare class IngressSnapshotCache {
+    private readonly options;
+    private hosts;
+    private snapshot;
+    private loadedAt;
+    private pending;
+    private timer;
+    private readonly intervalMs;
+    private readonly staleAfterMs;
+    private readonly now;
+    constructor(options: IngressSnapshotCacheOptions);
+    /** Pulls now and then every interval; the timer never keeps the process alive. */
+    start(): void;
+    stop(): void;
+    /** Single-flight: concurrent callers share one pull. Never rejects. */
+    refresh(): Promise<void>;
+    /** `host` must already be the canonical raw Host. A local map lookup; never a network call. */
+    lookup(host: string): IngressSnapshotLookup;
+    /** The non-secret per-provider summary the exchange precheck reads; undefined until a pull succeeds. */
+    get providers(): IngressSnapshot['providers'] | undefined;
+    /** The last pulled snapshot's policy epoch; a newer one on a grant asks for a pull now. */
+    get policyEpoch(): number | undefined;
+}

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;