Evenfire is an intelligence layer platform for running LLM agents that take real actions, on your infrastructure
TypeScript
import { createHash, randomUUID } from "node:crypto";
import type { IncomingMessage, ServerResponse } from "node:http";
import type { GfsVerifiedClaims } from "../auth/verify";
import type { AccessibleResourcePage } from "../authz/accessibleStore";
import type { AuditSink } from "../authz/audit";
import { type AuthzContext, auditAttribution } from "../authz/permissionClient";
import type { GfsPermission } from "../authz/resolve";
import { GfsSubjectResolutionDeniedError } from "../authz/subjectResolver";
import { checkTokenCeiling } from "../authz/tokenCeiling";
import type { GfsWriteService } from "../db/writeStore";
import { LogThrottle } from "../logThrottle";
import type { GfsMetrics } from "../metrics";
import { type RateLimiter, RateLimitExceededError } from "../quota/rateLimit";
import type {
GfsUploadPartGeometry,
GfsUploadSessionService,
UploadPartStatus,
UploadPrincipal,
UploadSessionReceipt,
} from "../upload/uploadSession";
import { normalizeResourceId, PathError } from "../storage/paths";
import { type CopyRouteDeps, executeCopyRoute } from "./copyRoute";
import { ok, toResponse } from "./envelope";
import { GfsError } from "./errors";
import {
BlobReader,
ResourceStore,
downloadResource,
listChildren,
statResource,
toView,
} from "./read";
import { executeRenameRoute } from "./renameRoute";
import { normalizeResourceName, ResourceNameError } from "./resourceName";
import { planWrite, WriteError } from "./write";
import { disabledGfsUploadV2Capability } from "../upload/protocol";
/**
* Strip control characters (CR/LF/tab, C0 controls, DEL) and bound the length of
* a user-controlled value before it is interpolated into a log line. Prevents
* log injection / log forging (CWE-117) when values that may carry user input
* (request method/target, or an error message/stack that echoes a decoded path)
* reach a log sink. CR/LF are removed; other control chars become '?'.
*/
export function sanitizeForLog(value: string): string {
// Remove CR/LF first (the log-forging vector; empty-string replace that
// enumerates \n is the barrier CodeQL's js/log-injection recognizes), then
// scrub any remaining C0 controls and DEL to '?', and bound the length to
// guard against log flooding.
return value
.replace(/[\n\r]/g, "")
.replace(/[\u0000-\u001f\u007f]/g, "?")
.slice(0, 512);
}
/**
* gfsc read serving handler (spec community.md §Operator surfaces / §Auth,
* plan P1-S07/S08 composed). This is the broker's READ data plane — the single
* place where a request is turned into a served byte or a denial.
*
* Every request runs the full governed chain, in order, FAIL-CLOSED at each hop:
*
* 1. Bearer token → verifyToken (sig/aud/exp, fail-closed → 401)
* 2. principal → subjects → resolveContext (DB; store error → 503)
* 3. agent rate limit → rateLimit.reads / rateLimit.writes, charged for
* host principals only, per attempt (→ 429)
* 4. token CEILING → checkTokenCeiling (scopes + pathBindings; the
* upper bound the token itself carries → 403)
* 5. permission STORE → PermissionClient.authorize (source of truth,
* deny-by-default, audited, fail-closed → 503)
* 6. executor → stat / list / download / mutation
*
* Step 3 runs before authorization, so a flood is bounded by attempts, not by
* successes, and a denied agent never reaches the permission store. User and
* linked-admin principals are not charged here. Desktop requests reach gfsc
* through control-api's /external/gfs routes, which meter every request before
* minting. The Control UI operator plane (control-api /api/v1/gfs/proxy) is
* metered by neither control-api nor gfsc today (#762).
*
* Steps 4 AND 5 must BOTH allow — "neither alone authorizes" (§522). Authz runs
* BEFORE any metadata is revealed, so an absent resource and an unauthorized one
* are indistinguishable (both 403) — no existence leak. The `drive` is taken
* from the token claim, never from the query, so a token can only ever reach the
* drive it was minted for.
*/
/** The verify/authorize/store collaborators, injected for isolated unit tests. */
export interface ServingDeps {
verifyToken: (token: string) => GfsVerifiedClaims;
resolveContext: (
claims: Pick<
GfsVerifiedClaims,
"sub" | "drive" | "brokeredAuthority" | "principalType" | "authGeneration"
>,
requestId?: string
) => Promise<AuthzContext>;
/** Permission-store authorization (the source of truth). */
authorize: (
ctx: AuthzContext,
resourceId: string,
op: GfsPermission
) => Promise<{ allowed: boolean }>;
/** Lists direct resources visible to the resolved principal. */
listAccessible?: (
ctx: AuthzContext,
opts: { limit?: unknown; cursor?: string }
) => Promise<AccessibleResourcePage>;
store: ResourceStore;
blobs: BlobReader;
/** The transactional write data plane. Absent on a read-only replica — write
* routes then respond 404 (the verb is not served), never a silent no-op. */
writeService?: GfsWriteService;
audit?: AuditSink;
copy?: Omit<CopyRouteDeps, "writes">;
/** Admission limits for the synchronous rename mutation; PATCH is not served without them. */
rename?: { maxObjects: number; timeoutMs: number };
metrics?: GfsMetrics;
/** Per-subject agent budgets (step 3 of the chain). Required: no caller can opt out. */
rateLimit: { reads: RateLimiter; writes: RateLimiter };
/** Injectable clock for deterministic latency tests; defaults to Date.now. */
now?: () => number;
/** Capability response is injected so PR1 can remain disabled and testable. */
uploadCapabilities?: () => GfsUploadCapabilities;
uploadService?: GfsUploadSessionService;
}
export interface GfsUploadCapabilities {
upload: {
legacyBase64: { enabled: true; maxFileBytes: number };
resumableV2: { enabled: boolean; [key: string]: unknown };
};
}
/**
* Largest mutation body gfsc accepts before failing loud with payload_too_large.
* Configurable via GFS_MAX_WRITE_BODY_BYTES, plumbed to the gfsc pod through the
* host-context-controller gfsc template (deploy sets it to 24MiB for the 16MB upload
* cap). A non-integer or non-positive value fails loud to stderr and falls back to the
* 16MiB default — otherwise a config typo would silently 413 every large upload.
*/
const DEFAULT_MAX_WRITE_BODY_BYTES = 16 * 1024 * 1024;
const MAX_WRITE_BODY_BYTES = ((): number => {
const rawEnv = process.env.GFS_MAX_WRITE_BODY_BYTES;
if (rawEnv === undefined) return DEFAULT_MAX_WRITE_BODY_BYTES;
const raw = Number(rawEnv);
if (Number.isInteger(raw) && raw > 0) return raw;
console.error(
`[gfsc] ignoring invalid GFS_MAX_WRITE_BODY_BYTES="${rawEnv}" (must be a positive integer); using ${DEFAULT_MAX_WRITE_BODY_BYTES}`
);
return DEFAULT_MAX_WRITE_BODY_BYTES;
})();
const MAX_NODE_TIMER_DELAY_MS = 2_147_483_647;
const NANOSECONDS_PER_MILLISECOND = 1_000_000n;
/**
* Node clamps larger timer delays to 1 ms. Re-arm the copy deadline in bounded
* chunks so the full positive safe-integer ENV contract remains meaningful.
* Each callback recomputes its remaining budget against an absolute monotonic
* deadline: event-loop stalls and machine suspension must not extend the copy.
*/
function armCopyAbortTimer(controller: AbortController, timeoutMs: number): () => void {
const deadlineNs = process.hrtime.bigint() + BigInt(timeoutMs) * NANOSECONDS_PER_MILLISECOND;
let timer: NodeJS.Timeout | undefined;
let cancelled = false;
const armNextChunk = (): void => {
const remainingNs = deadlineNs - process.hrtime.bigint();
if (remainingNs <= 0n) {
controller.abort(new GfsError("precondition_failed", "synchronous copy deadline exceeded"));
return;
}
// Round up so an early timer callback cannot expire the request before its
// monotonic deadline. The next callback recomputes rather than subtracting
// this nominal delay, which also handles delayed callbacks correctly.
const remainingMs = Number(
(remainingNs + NANOSECONDS_PER_MILLISECOND - 1n) / NANOSECONDS_PER_MILLISECOND
);
const delayMs = Math.min(remainingMs, MAX_NODE_TIMER_DELAY_MS);
timer = setTimeout(() => {
if (cancelled) return;
armNextChunk();
}, delayMs);
timer.unref();
};
armNextChunk();
return () => {
cancelled = true;
if (timer) clearTimeout(timer);
};
}
/** A host principal (`sub` starts with `host:`) is an AGENT — write invariants
* (mandatory If-Match on replace/delete) apply only to agents. */
function isAgentSub(sub: string): boolean {
return sub.startsWith("host:");
}
/** An agent retrying a denied request writes at most one denial line per kind per minute. */
const RATE_LIMIT_DENIAL_LOG_INTERVAL_MS = 60_000;
const RESOURCE_RE = /^\/v1\/resources\/([^/]+)(?:\/(children|content))?$/;
const RESOLVE_RE = /^\/v1\/resolve$/;
const ACCESSIBLE_RE = /^\/v1\/accessible$/;
const COPY_RE = /^\/v1\/copy$/;
const CAPABILITIES_RE = /^\/v1\/capabilities$/;
const UPLOAD_COLLECTION_RE = /^\/v1\/uploads$/;
const UPLOAD_ITEM_RE = /^\/v1\/uploads\/([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})(?:\/(status|parts\/([0-9]+)|pause|resume|complete))?$/i;
const GFS_URI_RE = /^gfs:\/\/([^/]+)\/([^/?#]+)$/;
function bearerToken(req: IncomingMessage): string {
const header = req.headers["authorization"];
if (typeof header !== "string" || !header.startsWith("Bearer ")) {
throw new GfsError("unauthorized", "missing or malformed Authorization: Bearer header");
}
const token = header.slice("Bearer ".length).trim();
if (token.length === 0) throw new GfsError("unauthorized", "empty bearer token");
return token;
}
/** Normalize a caller-supplied rid, mapping a bad value to 400 (not a 503). */
function requireRid(raw: string): string {
try {
return normalizeResourceId(decodeURIComponent(raw));
} catch (err) {
if (err instanceof PathError) throw new GfsError("path_invalid", err.message);
throw err;
}
}
function sendJson(
res: ServerResponse,
status: number,
body: unknown,
headers?: Record<string, string>
): void {
res.writeHead(status, { "Content-Type": "application/json", ...headers });
res.end(JSON.stringify(body));
}
/**
* When a response is written BEFORE the request body was fully received (e.g.
* payload_too_large aborts the read mid-stream), the connection cannot be
* reused: unread bytes are still in flight and Node resets the socket after
* the response. Without advertising `Connection: close`, a pooling client
* (undici in control-api's gfs proxy) queues its next request onto the
* about-to-die socket and gets ECONNRESET → a spurious 502 gfsc_unreachable
* (reproduced live: 413 → immediately-following proxied request failed
* deterministically). `req.complete` is Node's own "entire message received"
* flag; `=== false` keeps plain-object test doubles (complete: undefined)
* and fully-consumed bodies on normal keep-alive.
*/
function abortConnectionHeader(req: IncomingMessage): Record<string, string> | undefined {
return req.complete === false ? { Connection: "close" } : undefined;
}
export class GfsServingHandler {
/** Keyed by kind and hashed subject; bounds the rate_limit_denied line volume. */
private readonly denialLogThrottle: LogThrottle;
constructor(private readonly deps: ServingDeps) {
this.denialLogThrottle = new LogThrottle(RATE_LIMIT_DENIAL_LOG_INTERVAL_MS, () => this.clock());
}
private clock(): number {
return (this.deps.now ?? Date.now)();
}
/**
* Try to serve a read OR write route. Returns true iff the path matched a
* served route (handled — including an error response); false to let the
* caller fall through to its own 404. GET is read; POST/PUT/DELETE are writes
* (only when a writeService is configured). A matched path with an unsupported
* verb is a handled 404 — never a silent no-op.
*/
async tryHandle(req: IncomingMessage, res: ServerResponse): Promise<boolean> {
const url = new URL(req.url || "/", "http://gfsc.local");
const resourceMatch = RESOURCE_RE.exec(url.pathname);
const resolveMatch = RESOLVE_RE.exec(url.pathname);
const accessibleMatch = ACCESSIBLE_RE.exec(url.pathname);
const copyMatch = COPY_RE.exec(url.pathname);
const capabilitiesMatch = CAPABILITIES_RE.exec(url.pathname);
const uploadCollectionMatch = UPLOAD_COLLECTION_RE.exec(url.pathname);
const uploadItemMatch = UPLOAD_ITEM_RE.exec(url.pathname);
if (!resourceMatch && !resolveMatch && !accessibleMatch && !copyMatch && !capabilitiesMatch && !uploadCollectionMatch && !uploadItemMatch) return false;
const method = req.method ?? "GET";
const isWrite =
method === "POST" || method === "PUT" || method === "PATCH" || method === "DELETE";
const copyWrite = method === "POST" && copyMatch && this.deps.writeService && this.deps.copy;
const renameWrite =
method === "PATCH" &&
resourceMatch?.[2] === undefined &&
this.deps.writeService &&
this.deps.audit &&
this.deps.rename;
const resourceWrite =
isWrite &&
this.deps.writeService &&
resourceMatch &&
(method === "DELETE" || Boolean(this.deps.audit));
const uploadRoute = Boolean(uploadCollectionMatch || uploadItemMatch);
if (
(capabilitiesMatch && method !== "GET") ||
(copyMatch && !copyWrite) ||
(method === "PATCH" && !renameWrite) ||
(method !== "GET" && !resourceWrite && !copyWrite && !capabilitiesMatch && !uploadRoute)
) {
// This 404 can be written before a request body was consumed (e.g. a
// POST with a body to an unsupported verb/route) — same socket-poisoning
// risk as the catch path below, so it carries the same close semantics.
sendJson(
res,
404,
{ ok: false, error: { code: "not_found", message: "not found" } },
abortConnectionHeader(req)
);
return true;
}
const started = this.clock();
const copyAbort = copyWrite ? new AbortController() : undefined;
const cancelCopyTimer = copyAbort
? armCopyAbortTimer(copyAbort, this.deps.copy!.timeoutMs)
: undefined;
try {
const claims = this.deps.verifyToken(bearerToken(req));
const needsMutationRequestId =
Boolean(copyMatch) ||
Boolean(renameWrite) ||
Boolean(
resourceMatch &&
((method === "POST" && resourceMatch[2] === "children") ||
(method === "PUT" && resourceMatch[2] === "content"))
);
const requestId = needsMutationRequestId ? requireRequestId(req) : undefined;
const ctx = await this.authContext(claims, req, requestId);
this.chargeAgentBudget(
ctx,
Boolean(resourceWrite || copyWrite || renameWrite || (uploadRoute && isWrite))
);
copyAbort?.signal.throwIfAborted();
if (capabilitiesMatch) {
await this.serveCapabilities(res);
} else if (uploadRoute) {
await this.serveUpload(req, res, claims, ctx, method, url, uploadCollectionMatch, uploadItemMatch);
} else if (method === "GET") {
await this.handleRead(res, claims, ctx, url, resourceMatch, resolveMatch, accessibleMatch);
this.deps.metrics?.recordRead(this.clock() - started);
} else if (copyMatch) {
await this.serveCopy(req, res, claims, ctx, requestId!, started, copyAbort!.signal);
this.deps.metrics?.recordWrite(this.clock() - started);
} else {
await this.handleWrite(req, res, claims, ctx, method, resourceMatch!, requestId);
this.deps.metrics?.recordWrite(this.clock() - started);
}
} catch (err) {
const { status, body, rateLimitLimit } = toResponse(err);
if (status >= 500) {
// A 5xx must never be invisible: an unknown throw (e.g. the base64
// RangeError that produced a bogus `internal` 500) previously left no
// trace anywhere in the system. Log code + stack (never the body/content).
// The stack/message is sanitized too: an underlying error (e.g. a driver
// error echoing a decoded path) can carry user input with real newlines,
// so it is a log-injection source just like method/url.
console.error(
`[gfsc] ${sanitizeForLog(method)} ${sanitizeForLog(req.url ?? "?")} -> ${status} ${body.error.code}: ${sanitizeForLog(
err instanceof Error ? (err.stack ?? err.message ?? "") : String(err)
)}`
);
}
if (!res.headersSent) {
const retryAfter = body.error.retryAfterSeconds;
if (retryAfter !== undefined) res.setHeader("Retry-After", String(retryAfter));
if (rateLimitLimit !== undefined)
res.setHeader("X-RateLimit-Limit", String(rateLimitLimit));
if (body.error.limit !== undefined)
res.setHeader("X-GFS-RateLimit-Scope", body.error.limit);
sendJson(res, status, body, abortConnectionHeader(req));
}
else res.end(); // a content stream already started; just terminate
} finally {
cancelCopyTimer?.();
}
return true;
}
private async serveCapabilities(res: ServerResponse): Promise<void> {
const capabilities = this.deps.uploadCapabilities?.() ?? {
upload: {
legacyBase64: { enabled: true as const, maxFileBytes: 16 * 1024 * 1024 },
resumableV2: disabledGfsUploadV2Capability(),
},
};
sendJson(res, 200, capabilities, { "Cache-Control": "no-store" });
}
private async serveUpload(
req: IncomingMessage,
res: ServerResponse,
claims: GfsVerifiedClaims,
ctx: AuthzContext,
method: string,
url: URL,
collectionMatch: RegExpExecArray | null,
itemMatch: RegExpExecArray | null
): Promise<void> {
const service = this.deps.uploadService;
if (!service) throw new GfsError("not_mounted", "upload session service is unavailable");
const principal: UploadPrincipal = {
drive: claims.drive,
ownerSubject: claims.sub,
primarySubject: ctx.primarySubject,
...(claims.authGeneration === undefined ? {} : { authGeneration: claims.authGeneration }),
...(claims.principalType ? { principalType: claims.principalType } : {}),
...(claims.brokeredAuthority ? { brokeredAuthority: claims.brokeredAuthority } : {}),
};
// Session DELETE is a cancel action, not deletion of the GFS resource; the
// session's original write authority governs it just like pause/resume.
const sessionPermission: GfsPermission = "write";
const sessionCeiling = checkTokenCeiling({ scopes: claims.scopes, pathBindings: claims.pathBindings, op: sessionPermission, resourcePath: null });
if (!sessionCeiling.allowed && (claims.pathBindings.length === 0 || sessionCeiling.reason === "scope_not_in_token")) {
throw new GfsError("forbidden", `token does not authorize ${sessionPermission}`, sessionCeiling.reason);
}
if (collectionMatch) {
if (method !== "POST") throw new GfsError("not_found", `no ${method} route for upload collection`);
const body = await readJsonBody(req, { maxBytes: 64 * 1024 });
const operation = body.operation;
if (operation !== "create" && operation !== "replace") throw new GfsError("path_invalid", "operation must be create or replace");
const targetRid = operation === "create" ? optionalString(body, "parentRid") : optionalString(body, "resourceRid");
if (!targetRid) throw new GfsError("path_invalid", `${operation} requires its target`);
const ifMatch = optionalNumber(body, "ifMatch");
const plan = mapWritePlan(() => planWrite({
op: operation,
...(operation === "create" ? { parentId: targetRid } : { resourceId: targetRid }),
ifMatch,
isAgent: isAgentSub(claims.sub),
}));
await this.authorizeChecks(claims, ctx, plan.checks);
const sizeBytes = requireInteger(body, "sizeBytes");
const idempotencyKey = requireString(body, "idempotencyKey");
const session = await service.create({
...principal,
idempotencyKey,
operation,
sizeBytes,
parentRid: optionalString(body, "parentRid"),
resourceRid: optionalString(body, "resourceRid"),
name: optionalString(body, "name"),
ifMatch,
wholeSha256: optionalString(body, "wholeSha256") ?? null,
});
sendJson(res, session.created ? 201 : 200, ok(session.session), {
...uploadSessionHeaders(session.session),
Location: `/v1/uploads/${session.session.uploadId}`,
});
return;
}
const uploadId = itemMatch![1]!;
const action = itemMatch![2];
const target = await service.target(uploadId, principal);
if (!target.targetRid) throw new GfsError("path_invalid", "upload session target is missing");
await this.authorizeOp(claims, ctx, target.targetRid, sessionPermission);
if (method === "HEAD" && action === undefined) {
const session = await service.get(uploadId, principal);
res.writeHead(204, uploadSessionHeaders(session));
res.end();
return;
}
if (method === "GET" && action === "status") {
const rawLimit = url.searchParams.get("limit");
const parsedLimit = rawLimit === null ? null : Number(rawLimit);
if (parsedLimit !== null && (!Number.isSafeInteger(parsedLimit) || parsedLimit < 1 || parsedLimit > 256)) {
throw new GfsError("path_invalid", "status limit is invalid");
}
const cursor = url.searchParams.get("cursor") ?? undefined;
const status = await service.status(uploadId, principal, {
cursor,
...(parsedLimit === null ? {} : { limit: parsedLimit }),
});
sendJson(res, 200, ok(status), uploadSessionHeaders(status.session));
return;
}
if (method === "PUT" && action?.startsWith("parts/")) {
const partNumber = Number(itemMatch![3]);
const declaredPartNumber = requireHeaderInteger(req, "upload-part-number");
if (declaredPartNumber !== partNumber) throw new GfsError("path_invalid", "Upload-Part-Number must match the part path");
const offsetBytes = requireHeaderInteger(req, "upload-offset");
const lengthBytes = requireHeaderInteger(req, "upload-chunk-length");
const contentType = headerValue(req, "content-type")?.split(";", 1)[0]?.trim().toLowerCase();
if (contentType !== "application/offset+octet-stream") {
throw new GfsError("path_invalid", "content-type must be application/offset+octet-stream");
}
const contentLength = headerValue(req, "content-length");
if (contentLength !== undefined) {
const declaredContentLength = requireHeaderInteger(req, "content-length");
if (declaredContentLength !== lengthBytes) throw new GfsError("path_invalid", "Content-Length must match Upload-Chunk-Length");
}
const result = await service.putPart(uploadId, { partNumber, offsetBytes, lengthBytes }, parseUploadChecksum(headerValue(req, "upload-checksum")), req, principal);
res.writeHead(204, uploadPartHeaders(result.session, result.part));
res.end();
return;
}
if (method === "POST" && (action === "pause" || action === "resume")) {
const session = action === "pause" ? await service.pause(uploadId, principal) : await service.resume(uploadId, principal);
sendJson(res, 200, ok(session), uploadSessionHeaders(session));
return;
}
if (method === "POST" && action === "complete") {
const body = await readJsonBody(req, { allowEmpty: true, maxBytes: 16 * 1024 });
const session = await service.complete(uploadId, principal, optionalString(body, "wholeSha256"));
sendJson(res, session.operation === "create" ? 201 : 200, ok(session), uploadSessionHeaders(session));
return;
}
if (method === "DELETE" && action === undefined) {
await service.cancel(uploadId, principal);
res.writeHead(204, { "Cache-Control": "no-store" });
res.end();
return;
}
throw new GfsError("not_found", `no ${method} route for upload session`);
}
private async handleRead(
res: ServerResponse,
claims: GfsVerifiedClaims,
ctx: AuthzContext,
url: URL,
resourceMatch: RegExpExecArray | null,
resolveMatch: RegExpExecArray | null,
accessibleMatch: RegExpExecArray | null
): Promise<void> {
if (accessibleMatch) {
await this.serveAccessible(res, claims, ctx, url);
return;
}
if (resolveMatch) {
await this.serveResolve(res, claims, ctx, url);
return;
}
const rid = requireRid(resourceMatch![1]);
const sub = resourceMatch![2]; // undefined | "children" | "content"
if (sub === "children") {
await this.serveChildren(res, claims, ctx, rid, url);
} else if (sub === "content") {
await this.serveContent(res, claims, ctx, rid);
} else {
await this.serveStat(res, claims, ctx, rid);
}
}
/**
* Dispatch a mutation. The route + verb fix the write op:
* POST /v1/resources/:parentId/children → create
* PUT /v1/resources/:id/content → replace
* DELETE /v1/resources/:id → delete
* Every mutation runs planWrite (agent If-Match invariant + which permission
* the op needs), then the SAME governed authz chain as reads for each required
* check, then the transactional write service.
*/
private async handleWrite(
req: IncomingMessage,
res: ServerResponse,
claims: GfsVerifiedClaims,
ctx: AuthzContext,
method: string,
resourceMatch: RegExpExecArray,
requestId?: string
): Promise<void> {
const rid = requireRid(resourceMatch[1]);
const sub = resourceMatch[2]; // undefined | "children" | "content"
if (method === "POST" && sub === "children") {
await this.serveCreate(req, res, claims, ctx, rid, requestId!);
} else if (method === "PUT" && sub === "content") {
await this.serveReplace(req, res, claims, ctx, rid, requestId!);
} else if (method === "PATCH" && sub === undefined) {
await this.serveRename(req, res, claims, ctx, rid, requestId!);
} else if (method === "DELETE" && sub === undefined) {
await this.serveDelete(req, res, claims, ctx, rid);
} else {
throw new GfsError("not_found", `no ${method} route for this resource path`);
}
}
/**
* Step 3: spend one unit of the agent's write or read budget. Only host
* principals are charged; after authContext a `host:` subject has matched the
* canonical host form. A denial is counted, logged with the subject hashed,
* and answered 429 with the limiter's own limit and retry-after. The counter
* sees every denial; the log line is throttled to one per subject and kind
* per minute and carries how many lines it suppressed since the previous one.
*/
private chargeAgentBudget(ctx: AuthzContext, write: boolean): void {
if (!isAgentSub(ctx.primarySubject)) return;
const kind = write ? "write" : "read";
const limiter = write ? this.deps.rateLimit.writes : this.deps.rateLimit.reads;
try {
limiter.check(ctx.primarySubject);
} catch (err) {
if (!(err instanceof RateLimitExceededError)) throw err;
this.deps.metrics?.recordRateLimitDenial(kind);
// The hash is a correlation id, not anonymization: host subjects are
// enumerable, so anyone holding the host list can reverse it. Hex output
// needs no log sanitizing.
const hashedSubject = createHash("sha256").update(ctx.primarySubject).digest("hex");
const suppressed = this.denialLogThrottle.admit(`${kind}:${hashedSubject}`);
if (suppressed !== undefined) {
console.warn(`[gfsc] rate_limit_denied kind=${kind} subject=${hashedSubject} suppressed=${suppressed}`);
}
throw new GfsError("rate_limited", "agent rate limit exceeded", undefined, {
retryAfterSeconds: err.retryAfterSeconds,
limit: write ? "agent_writes" : "agent_reads",
rateLimitLimit: limiter.limitPerWindow,
});
}
}
/** Resolve the principal to its subject set; a store failure is fail-closed 503. */
private async authContext(
claims: GfsVerifiedClaims,
req: IncomingMessage,
admittedRequestId?: string
): Promise<AuthzContext> {
const requestId = admittedRequestId ?? headerValue(req, "x-request-id");
try {
return await this.deps.resolveContext(
{
sub: claims.sub,
drive: claims.drive,
...(claims.brokeredAuthority ? { brokeredAuthority: claims.brokeredAuthority } : {}),
...(claims.principalType ? { principalType: claims.principalType } : {}),
...(claims.authGeneration === undefined ? {} : { authGeneration: claims.authGeneration }),
},
requestId
);
} catch (err) {
if (err instanceof GfsSubjectResolutionDeniedError) {
throw new GfsError("forbidden", "principal is not authorized for GFS");
}
throw new GfsError(
"not_mounted",
`subject resolution failed: ${err instanceof Error ? err.message : String(err)}`
);
}
}
/**
* Enforce BOTH authority layers for `op` on `rid`: the token ceiling (the
* upper bound the token carries) AND the permission store (the source of
* truth). Throws `forbidden` if either denies. The resource path is fetched
* for the ceiling ONLY when the token actually declares pathBindings (P2+);
* P1 tokens carry none, so this is a pure in-memory check.
*/
private async authorizeOp(
claims: GfsVerifiedClaims,
ctx: AuthzContext,
rid: string,
op: GfsPermission
): Promise<void> {
let resourcePath: string | null = null;
if (claims.pathBindings.length > 0) {
const resource = await this.deps.store.getResource(claims.drive, rid);
resourcePath = resource?.pathCache ?? null;
}
const ceiling = checkTokenCeiling({
scopes: claims.scopes,
pathBindings: claims.pathBindings,
op,
resourcePath,
});
if (!ceiling.allowed) {
throw new GfsError("forbidden", `token does not authorize ${op}`, ceiling.reason);
}
const decision = await this.deps.authorize(ctx, rid, op);
if (!decision.allowed) {
throw new GfsError("forbidden", `not authorized to ${op} this resource`);
}
}
private async serveAccessible(
res: ServerResponse,
claims: GfsVerifiedClaims,
ctx: AuthzContext,
url: URL
): Promise<void> {
const ceiling = checkTokenCeiling({
scopes: claims.scopes,
pathBindings: claims.pathBindings,
op: "read",
resourcePath: null,
});
if (!ceiling.allowed) {
throw new GfsError(
"forbidden",
"read scope is required for accessible-resource discovery",
ceiling.reason
);
}
if (!this.deps.listAccessible) {
throw new GfsError("not_mounted", "accessible-resource store is unavailable");
}
const page = await this.deps.listAccessible(ctx, {
limit: url.searchParams.get("limit") ?? undefined,
cursor: url.searchParams.get("cursor") ?? undefined,
});
sendJson(res, 200, ok(page));
}
private async serveStat(
res: ServerResponse,
claims: GfsVerifiedClaims,
ctx: AuthzContext,
rid: string
): Promise<void> {
await this.authorizeOp(claims, ctx, rid, "read");
const view = await statResource(this.deps.store, claims.drive, rid);
sendJson(res, 200, ok(view));
}
private async serveChildren(
res: ServerResponse,
claims: GfsVerifiedClaims,
ctx: AuthzContext,
rid: string,
url: URL
): Promise<void> {
await this.authorizeOp(claims, ctx, rid, "read");
const page = await listChildren(this.deps.store, claims.drive, rid, {
limit: url.searchParams.get("limit") ?? undefined,
cursor: url.searchParams.get("cursor") ?? undefined,
});
sendJson(res, 200, ok(page));
}
private async serveContent(
res: ServerResponse,
claims: GfsVerifiedClaims,
ctx: AuthzContext,
rid: string
): Promise<void> {
await this.authorizeOp(claims, ctx, rid, "read");
const { resource, stream } = await downloadResource(
this.deps.store,
this.deps.blobs,
claims.drive,
rid
);
res.writeHead(200, {
"Content-Type": "application/octet-stream",
"Content-Length": String(resource.bytes),
"X-Gfs-Uri": resource.gfsUri,
"X-Gfs-Version": String(resource.version),
});
stream.pipe(res);
// Surface a mid-stream read error instead of silently truncating the body.
// pipe() does not propagate destination close back to the source, so a
// client abort must destroy the blob stream or its fd stays open.
await new Promise<void>((resolve, reject) => {
stream.on("end", resolve);
stream.on("error", reject);
res.on("close", () => {
stream.destroy();
resolve();
});
});
}
private async serveResolve(
res: ServerResponse,
claims: GfsVerifiedClaims,
ctx: AuthzContext,
url: URL
): Promise<void> {
const uri = url.searchParams.get("uri");
if (!uri) throw new GfsError("path_invalid", "resolve requires a ?uri=gfs://<drive>/<rid>");
const m = GFS_URI_RE.exec(uri);
if (!m) throw new GfsError("path_invalid", `not a gfs:// uri: ${uri}`);
const [, uriDrive, rawRid] = m;
if (uriDrive !== claims.drive) {
// The token is scoped to one drive; resolving across drives is denied,
// not a 404 — never confirm existence on a drive the token cannot reach.
throw new GfsError("forbidden", `token is scoped to drive ${claims.drive}, not ${uriDrive}`);
}
const rid = requireRid(rawRid);
await this.authorizeOp(claims, ctx, rid, "read");
const view = await statResource(this.deps.store, claims.drive, rid);
sendJson(res, 200, ok(view));
}
// ── Write routes ────────────────────────────────────────────────────────────
private async serveCopy(
req: IncomingMessage,
res: ServerResponse,
claims: GfsVerifiedClaims,
ctx: AuthzContext,
requestId: string,
admittedAtMs: number,
signal: AbortSignal
): Promise<void> {
const body = await readJsonBody(req, { signal });
const data = await executeCopyRoute({
body,
claims,
context: ctx,
requestId,
admittedAtMs,
signal,
now: () => this.clock(),
deps: { ...this.deps.copy!, writes: this.deps.writeService! },
});
sendJson(res, 201, ok(data));
}
private async serveCreate(
req: IncomingMessage,
res: ServerResponse,
claims: GfsVerifiedClaims,
ctx: AuthzContext,
parentId: string,
requestId: string
): Promise<void> {
const body = await readJsonBody(req);
const name = requireName(body, "name");
const kind = optionalResourceKind(body);
const content = kind === "directory" ? undefined : readContentBuffer(body);
// create needs `write` on the destination PARENT; no prior version → no
// If-Match even for an agent.
const plan = mapWritePlan(() =>
planWrite({ op: "create", parentId, isAgent: isAgentSub(claims.sub) })
);
await this.authorizeChecks(claims, ctx, plan.checks);
const created = await this.deps.writeService!.create({
drive: claims.drive,
parentId,
name,
kind,
content,
mutation: {
subject: ctx.primarySubject,
requestId,
audit: this.deps.audit!,
...auditAttribution(ctx),
},
});
sendJson(res, 201, ok(toView(created)));
}
private async serveReplace(
req: IncomingMessage,
res: ServerResponse,
claims: GfsVerifiedClaims,
ctx: AuthzContext,
resourceId: string,
requestId: string
): Promise<void> {
const body = await readJsonBody(req);
const content = readContentBuffer(body);
const ifMatch = optionalNumber(body, "ifMatch");
const plan = mapWritePlan(() =>
planWrite({ op: "replace", resourceId, ifMatch, isAgent: isAgentSub(claims.sub) })
);
await this.authorizeChecks(claims, ctx, plan.checks);
const updated = await this.deps.writeService!.replace({
drive: claims.drive,
resourceId,
ifMatch,
content,
mutation: {
subject: ctx.primarySubject,
requestId,
audit: this.deps.audit!,
...auditAttribution(ctx),
},
});
sendJson(res, 200, ok(toView(updated)));
}
private async serveRename(
req: IncomingMessage,
res: ServerResponse,
claims: GfsVerifiedClaims,
ctx: AuthzContext,
resourceId: string,
requestId: string
): Promise<void> {
const body = await readJsonBody(req);
const data = await executeRenameRoute({
body,
claims,
context: ctx,
resourceId,
requestId,
audit: this.deps.audit!,
authorizeWrite: () => this.authorizeOp(claims, ctx, resourceId, "write"),
writes: this.deps.writeService!,
limits: this.deps.rename!,
});
sendJson(res, 200, ok(data));
}
private async serveDelete(
req: IncomingMessage,
res: ServerResponse,
claims: GfsVerifiedClaims,
ctx: AuthzContext,
resourceId: string
): Promise<void> {
const body = await readJsonBody(req, { allowEmpty: true });
const ifMatch = optionalNumber(body, "ifMatch");
// delete needs the DESTRUCTIVE `delete` bit (agents are default-denied it).
const plan = mapWritePlan(() =>
planWrite({ op: "delete", resourceId, ifMatch, isAgent: isAgentSub(claims.sub) })
);
await this.authorizeChecks(claims, ctx, plan.checks);
await this.deps.writeService!.delete({ drive: claims.drive, resourceId, ifMatch });
sendJson(res, 200, ok({ deleted: true, resourceId }));
}
/** Run the governed authz chain (ceiling + store) for every required check. */
private async authorizeChecks(
claims: GfsVerifiedClaims,
ctx: AuthzContext,
checks: Array<{ resourceId: string; op: GfsPermission }>
): Promise<void> {
for (const check of checks) {
await this.authorizeOp(claims, ctx, requireRid(check.resourceId), check.op);
}
}
}
function requireRequestId(req: IncomingMessage): string {
const supplied = headerValue(req, "x-request-id");
if (supplied === undefined) return randomUUID();
const normalized = requireRid(supplied);
return [
normalized.slice(0, 8),
normalized.slice(8, 12),
normalized.slice(12, 16),
normalized.slice(16, 20),
normalized.slice(20),
].join("-");
}
function headerValue(req: IncomingMessage, name: string): string | undefined {
const v = req.headers[name];
return typeof v === "string" ? v : undefined;
}
/** Map a WriteError (plan-time invariant) to its envelope GfsError. */
function mapWritePlan<T>(plan: () => T): T {
try {
return plan();
} catch (err) {
if (err instanceof WriteError) {
const code = err.code === "invalid_request" ? "path_invalid" : "precondition_failed";
throw new GfsError(code, err.message);
}
throw err;
}
}
function requireString(body: Record<string, unknown>, key: string): string {
const value = body[key];
if (typeof value !== "string") throw new GfsError("path_invalid", `'${key}' must be a string`);
return value;
}
function optionalString(body: Record<string, unknown>, key: string): string | undefined {
const value = body[key]
if (value === undefined || value === null) return undefined
if (typeof value !== "string") throw new GfsError("path_invalid", `'${key}' must be a string`)
return value
}
function requireInteger(body: Record<string, unknown>, key: string): number {
const value = body[key]
if (typeof value !== "number" || !Number.isSafeInteger(value)) {
throw new GfsError("path_invalid", `'${key}' must be an integer`)
}
return value
}
function requireHeaderInteger(req: IncomingMessage, name: string): number {
const raw = headerValue(req, name)
if (raw === undefined || !/^[0-9]+$/.test(raw)) throw new GfsError("path_invalid", `${name} must be a non-negative integer header`)
const value = Number(raw)
if (!Number.isSafeInteger(value)) throw new GfsError("path_invalid", `${name} is outside the safe integer range`)
return value
}
function uploadSessionHeaders(session: UploadSessionReceipt): Record<string, string> {
return {
"Cache-Control": "no-store",
"Upload-Offset": String(session.contiguousBytes),
"Upload-Length": String(session.expectedBytes),
"Upload-Part-Bytes": String(session.partBytes),
"Upload-Part-Count": String(session.partCount),
"Upload-Active-Parts": String(session.activePartCount),
"Upload-State": session.state,
"Upload-Expires": session.expiresAt,
}
}
function uploadPartHeaders(session: UploadSessionReceipt, part: UploadPartStatus): Record<string, string> {
return {
...uploadSessionHeaders(session),
"Upload-Part-Number": String(part.partNumber),
"Upload-Part-Offset": String(part.offsetBytes),
"Upload-Part-Length": String(part.lengthBytes),
"Upload-Checksum": `sha256 ${Buffer.from(part.sha256, "hex").toString("base64")}`,
}
}
function parseUploadChecksum(value: string | undefined): string {
if (value === undefined) throw new GfsError("path_invalid", "Upload-Checksum must be sha256 <base64 digest>");
const match = /^sha256\s+([A-Za-z0-9+/]{43}={1})$/.exec(value.trim());
if (!match) throw new GfsError("path_invalid", "Upload-Checksum must be sha256 <base64 digest>");
const decoded = Buffer.from(match[1], "base64");
if (decoded.length !== 32) throw new GfsError("path_invalid", "Upload-Checksum must contain a SHA-256 digest");
return decoded.toString("hex");
}
function optionalResourceKind(body: Record<string, unknown>): "file" | "directory" {
const value = body.kind;
if (value === undefined || value === null) return "file";
if (value === "file" || value === "directory") return value;
throw new GfsError("path_invalid", "'kind' must be 'file' or 'directory'");
}
function readContentBuffer(body: Record<string, unknown>): Buffer {
const encoded = body.contentBase64;
if (encoded !== undefined) {
if (typeof encoded !== "string")
throw new GfsError("path_invalid", "'contentBase64' must be a string");
return decodeBase64Content(encoded);
}
return Buffer.from(requireString(body, "content"), "utf8");
}
function decodeBase64Content(encoded: string): Buffer {
if (encoded.length === 0) return Buffer.alloc(0);
// Canonical base64: length is a multiple of 4, only base64 chars, and padding
// ('=' x0-2) only at the very end. This uses a single character-class star,
// which V8 compiles to a linear loop. The previous `/(?:[A-Za-z0-9+/]{4})*.../`
// used a GROUPED quantifier that pushes an Irregexp backtrack frame per 4-char
// group and threw `RangeError: Maximum call stack size exceeded` above ~4.47M
// chars (~3.2MB raw) — surfacing as a bogus 500 `internal` on any large upload.
if (encoded.length % 4 !== 0 || !/^[A-Za-z0-9+/]*={0,2}$/.test(encoded)) {
throw new GfsError("path_invalid", "'contentBase64' must be valid base64");
}
return Buffer.from(encoded, "base64");
}
function requireName(body: Record<string, unknown>, key: string): string {
try {
return normalizeResourceName(requireString(body, key));
} catch (err) {
if (err instanceof ResourceNameError) throw new GfsError("path_invalid", err.message);
throw err;
}
}
function optionalNumber(body: Record<string, unknown>, key: string): number | undefined {
const value = body[key];
if (value === undefined || value === null) return undefined;
if (typeof value !== "number" || !Number.isSafeInteger(value) || value < 0) {
throw new GfsError("path_invalid", `'${key}' must be an integer`);
}
return value;
}
/**
* Read a JSON request body, bounded by MAX_WRITE_BODY_BYTES (a write that
* exceeds it fails loud with payload_too_large rather than buffering without
* limit). A non-JSON or unparseable body is path_invalid.
*/
async function readJsonBody(
req: IncomingMessage,
opts: { allowEmpty?: boolean; signal?: AbortSignal; maxBytes?: number } = {}
): Promise<Record<string, unknown>> {
const chunks: Buffer[] = [];
let total = 0;
const abort = (): void => {
req.destroy(
opts.signal?.reason instanceof Error
? opts.signal.reason
: new GfsError("precondition_failed", "synchronous copy deadline exceeded")
);
};
opts.signal?.throwIfAborted();
opts.signal?.addEventListener("abort", abort, { once: true });
try {
for await (const chunk of req) {
opts.signal?.throwIfAborted();
const buf = chunk as Buffer;
total += buf.length;
const maxBytes = opts.maxBytes ?? MAX_WRITE_BODY_BYTES;
if (total > maxBytes) {
throw new GfsError("payload_too_large", `request body exceeds ${maxBytes} bytes`);
}
chunks.push(buf);
}
} finally {
opts.signal?.removeEventListener("abort", abort);
}
opts.signal?.throwIfAborted();
const raw = Buffer.concat(chunks).toString("utf8").trim();
if (raw === "") {
if (opts.allowEmpty) return {};
throw new GfsError("path_invalid", "request body is required");
}
try {
const parsed = JSON.parse(raw) as unknown;
if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
throw new Error("body must be a JSON object");
}
return parsed as Record<string, unknown>;
} catch (err) {
throw new GfsError(
"path_invalid",
`invalid JSON body: ${err instanceof Error ? err.message : String(err)}`
);
}
}