@beignet/core 0.0.32 → 0.0.33

package/src/server/trusted-proxy.ts

@@ -0,0 +1,249 @@
+import type { HttpRequestLike } from "./http.js";
+
+/**
+ * Header source used to resolve a client IP after an app has explicitly opted
+ * into trusting its deployment proxy or edge.
+ */
+export type TrustedProxyClientIpSource =
+  | "x-forwarded-for-last"
+  | "x-forwarded-for-first"
+  | "x-real-ip"
+  | "cf-connecting-ip"
+  | { header: string }
+  | ((req: HttpRequestLike) => string | undefined);
+
+/**
+ * Trusted proxy configuration for request metadata.
+ *
+ * Beignet trusts no forwarding headers by default. Configure this only when
+ * the app is always behind a platform or reverse proxy that strips or
+ * normalizes these headers before they reach application code.
+ */
+export interface TrustedProxyOptions {
+  /**
+   * Header source for the end-user client IP. Omit or set to `false` when no
+   * client-IP header should be trusted.
+   */
+  clientIp?: TrustedProxyClientIpSource | false;
+  /**
+   * Header that carries the external request protocol.
+   *
+   * Defaults to `x-forwarded-proto` when trusted proxy handling is enabled.
+   */
+  protocolHeader?: string | false;
+  /**
+   * Header that carries the external request host.
+   *
+   * Defaults to `x-forwarded-host` when trusted proxy handling is enabled.
+   */
+  hostHeader?: string | false;
+}
+
+/**
+ * Set to `false` or omit the config to trust no forwarding headers.
+ */
+export type TrustedProxyConfig = false | TrustedProxyOptions;
+
+/**
+ * Request metadata after applying an explicit trusted-proxy policy.
+ */
+export interface TrustedRequestInfo {
+  /**
+   * URL as seen by the app or reconstructed from trusted proxy headers.
+   */
+  url: URL;
+  /**
+   * External request origin.
+   */
+  origin: string;
+  /**
+   * External request protocol without a trailing colon.
+   */
+  protocol: "http" | "https";
+  /**
+   * External request host, including port when present.
+   */
+  host: string;
+  /**
+   * Resolved client IP when a trusted client-IP source is configured.
+   */
+  clientIp?: string;
+  /**
+   * Whether forwarding headers were eligible to affect this result.
+   */
+  trustedProxy: boolean;
+}
+
+const DEFAULT_PROTOCOL_HEADER = "x-forwarded-proto";
+const DEFAULT_HOST_HEADER = "x-forwarded-host";
+
+function splitForwardedHeader(value: string | null): string[] {
+  if (!value) return [];
+  return value
+    .split(",")
+    .map((entry) => entry.trim())
+    .filter(Boolean);
+}
+
+function firstHeaderValue(
+  req: HttpRequestLike,
+  header: string,
+): string | undefined {
+  return splitForwardedHeader(req.headers.get(header))[0];
+}
+
+function requireHeaderName(name: string, optionName: string): string {
+  const header = name.trim();
+  if (!header) {
+    throw new Error(`${optionName} must be a non-empty header name.`);
+  }
+  return header;
+}
+
+function normalizeProtocol(
+  value: string | undefined,
+): "http" | "https" | undefined {
+  if (!value) return undefined;
+  const protocol = value.toLowerCase().replace(/:$/, "");
+  if (protocol === "http" || protocol === "https") return protocol;
+  return undefined;
+}
+
+function hasInvalidHostCharacter(value: string): boolean {
+  for (const char of value) {
+    const code = char.charCodeAt(0);
+    if (
+      code <= 32 ||
+      code === 127 ||
+      char === "/" ||
+      char === "\\" ||
+      char === "@" ||
+      char === "?" ||
+      char === "#"
+    ) {
+      return true;
+    }
+  }
+  return false;
+}
+
+function normalizeHost(
+  value: string | undefined,
+  protocol: "http" | "https",
+): string | undefined {
+  if (!value || hasInvalidHostCharacter(value)) {
+    return undefined;
+  }
+
+  try {
+    return new URL(`${protocol}://${value}`).host;
+  } catch {
+    return undefined;
+  }
+}
+
+function baseRequestUrl(req: HttpRequestLike): URL {
+  try {
+    return new URL(req.url);
+  } catch {
+    throw new Error("req.url must be an absolute URL.");
+  }
+}
+
+function normalizedBaseProtocol(url: URL): "http" | "https" {
+  const protocol = normalizeProtocol(url.protocol);
+  if (protocol) return protocol;
+  throw new Error("req.url must use http or https.");
+}
+
+/**
+ * Resolve a client IP from a configured trusted proxy source.
+ */
+export function resolveTrustedClientIp(
+  req: HttpRequestLike,
+  source: TrustedProxyClientIpSource | false | undefined,
+): string | undefined {
+  if (!source) return undefined;
+
+  if (typeof source === "function") {
+    return source(req)?.trim() || undefined;
+  }
+
+  if (typeof source === "object") {
+    return firstHeaderValue(
+      req,
+      requireHeaderName(source.header, "trustedProxy.clientIp.header"),
+    );
+  }
+
+  if (source === "x-forwarded-for-first" || source === "x-forwarded-for-last") {
+    const entries = splitForwardedHeader(req.headers.get("x-forwarded-for"));
+    if (entries.length === 0) return undefined;
+    return source === "x-forwarded-for-first"
+      ? entries[0]
+      : entries[entries.length - 1];
+  }
+
+  return firstHeaderValue(req, source);
+}
+
+/**
+ * Resolve request metadata using only app-visible URL data unless a trusted
+ * proxy policy is explicitly configured.
+ */
+export function resolveTrustedRequest(
+  req: HttpRequestLike,
+  config: TrustedProxyConfig | undefined = false,
+): TrustedRequestInfo {
+  const baseUrl = baseRequestUrl(req);
+  const baseProtocol = normalizedBaseProtocol(baseUrl);
+  const baseHost = baseUrl.host;
+
+  if (!config) {
+    return {
+      url: baseUrl,
+      origin: baseUrl.origin,
+      protocol: baseProtocol,
+      host: baseHost,
+      trustedProxy: false,
+    };
+  }
+
+  const protocolHeader =
+    config.protocolHeader === false
+      ? undefined
+      : requireHeaderName(
+          config.protocolHeader ?? DEFAULT_PROTOCOL_HEADER,
+          "trustedProxy.protocolHeader",
+        );
+  const hostHeader =
+    config.hostHeader === false
+      ? undefined
+      : requireHeaderName(
+          config.hostHeader ?? DEFAULT_HOST_HEADER,
+          "trustedProxy.hostHeader",
+        );
+
+  const protocol =
+    normalizeProtocol(
+      protocolHeader ? firstHeaderValue(req, protocolHeader) : undefined,
+    ) ?? baseProtocol;
+  const host =
+    normalizeHost(
+      hostHeader ? firstHeaderValue(req, hostHeader) : undefined,
+      protocol,
+    ) ?? baseHost;
+  const url = new URL(baseUrl);
+  url.protocol = `${protocol}:`;
+  url.host = host;
+  const clientIp = resolveTrustedClientIp(req, config.clientIp);
+
+  return {
+    url,
+    origin: url.origin,
+    protocol,
+    host,
+    ...(clientIp !== undefined ? { clientIp } : {}),
+    trustedProxy: true,
+  };
+}

package/src/tasks/index.ts

@@ -1,4 +1,6 @@
 import type { StandardSchemaV1 } from "@standard-schema/spec";
+import { runWithResolvedTracingContext } from "../tracing/execution.js";
+import type { TracingPort } from "../tracing/index.js";
 
 /**
  * Any Standard Schema compatible validator.
@@ -75,9 +77,7 @@ export interface TaskHandleArgs<T extends TaskDef, Ctx> {
    * Parsed task input.
    */
   input: InferTaskInput<T>;
-  /**
-   * Handler context.
-   */
+  /** Handler context. */
   ctx: Ctx;
 }
 
@@ -115,10 +115,10 @@ export interface RunTaskOptions<Ctx> {
    * handler runs.
    */
   input: unknown;
-  /**
-   * Handler context.
-   */
-  ctx: Ctx;
+  /** Handler context or factory resolved inside the task span. */
+  ctx: Ctx | (() => MaybePromise<Ctx>);
+  /** Runtime tracing port used before a lazy context factory runs. */
+  tracing?: TracingPort;
 }
 
 /**
@@ -260,12 +260,29 @@ export async function runTask<
   T extends TaskDef<string, StandardSchema, Ctx>,
   Ctx,
 >(task: T, options: RunTaskOptions<Ctx>): Promise<InferTaskOutput<T>> {
-  const parsed = await parseTaskInput(task, options.input);
-  return (await task.handle({
-    task,
-    input: parsed,
+  const traceAttributes = {
+    "beignet.task.name": task.name,
+  } as const;
+
+  return await runWithResolvedTracingContext({
+    tracing: options.tracing,
     ctx: options.ctx,
-  })) as InferTaskOutput<T>;
+    operation: {
+      name: `beignet.task ${task.name}`,
+      type: "task",
+      kind: "internal",
+      attributes: traceAttributes,
+      metricAttributes: traceAttributes,
+    },
+    run: async (ctx) => {
+      const parsed = await parseTaskInput(task, options.input);
+      return (await task.handle({
+        task,
+        input: parsed,
+        ctx,
+      })) as InferTaskOutput<T>;
+    },
+  });
 }
 
 /**

package/src/tenancy/index.ts

@@ -0,0 +1,55 @@
+import type { ActivityTenant } from "../ports/audit.js";
+import { type RequireOptions, requireTenant } from "../ports/auth.js";
+
+const tenantScopeBrand = Symbol("TenantScope");
+
+/**
+ * Branded tenant scope token for repository boundaries.
+ *
+ * Apps still own tenant resolution and tenant data modeling. `TenantScope`
+ * carries the already-resolved activity tenant through app-facing repository
+ * ports so adapters can apply tenant predicates without accepting arbitrary
+ * caller-provided tenant IDs.
+ */
+export type TenantScope = Readonly<{
+  id: string;
+  tenant: ActivityTenant;
+  readonly [tenantScopeBrand]: true;
+}>;
+
+/**
+ * Create a tenant scope from a resolved activity tenant.
+ *
+ * This does not load, create, or validate a tenant record. It only brands the
+ * already-resolved tenant for repository and adapter boundaries.
+ */
+export function createTenantScope(tenant: ActivityTenant): TenantScope {
+  return {
+    id: tenant.id,
+    tenant,
+    [tenantScopeBrand]: true,
+  };
+}
+
+/**
+ * Return a branded tenant scope from `ctx.tenant` or throw.
+ *
+ * Throws `TenantRequiredError` by default through `requireTenant`. Pass
+ * `options.error` to throw an app-owned error instead.
+ */
+export function requireTenantScope(
+  ctx: { tenant?: ActivityTenant | null },
+  options?: RequireOptions,
+): TenantScope {
+  return createTenantScope(requireTenant(ctx, options));
+}
+
+/**
+ * Extract the stable tenant ID from a tenant scope.
+ *
+ * Repository adapters should use this helper at the persistence boundary
+ * instead of accepting raw tenant IDs from use cases.
+ */
+export function tenantScopeId(scope: TenantScope): string {
+  return scope.id;
+}

package/src/tracing/execution.ts

@@ -0,0 +1,37 @@
+import {
+  resolveTracingPort,
+  runWithTracing,
+  type TraceOperation,
+  type TraceSpan,
+  type TracingPort,
+} from "./index.js";
+
+type MaybePromise<T> = T | Promise<T>;
+
+/**
+ * Resolve a lazy application context inside a span when the runtime tracing
+ * port is available independently from that context.
+ */
+export async function runWithResolvedTracingContext<Ctx, Result>(args: {
+  tracing?: TracingPort;
+  ctx: Ctx | (() => MaybePromise<Ctx>);
+  operation: TraceOperation;
+  run(ctx: Ctx, span?: TraceSpan): MaybePromise<Result>;
+}): Promise<Result> {
+  const resolveContext = async (): Promise<Ctx> =>
+    typeof args.ctx === "function"
+      ? await (args.ctx as () => MaybePromise<Ctx>)()
+      : args.ctx;
+
+  if (args.tracing) {
+    return await runWithTracing(args.tracing, args.operation, async (span) =>
+      args.run(await resolveContext(), span),
+    );
+  }
+
+  const ctx = await resolveContext();
+  const tracing = resolveTracingPort(ctx);
+  return await runWithTracing(tracing, args.operation, (span) =>
+    args.run(ctx, span),
+  );
+}

package/src/tracing/index.ts

@@ -30,6 +30,10 @@ export interface TraceContext {
    * W3C traceparent header value.
    */
   traceparent: string;
+  /**
+   * Optional W3C tracestate value associated with this context.
+   */
+  tracestate?: string;
 }
 
 /**
@@ -62,6 +66,137 @@ export interface TraceContextInput {
   spanId?: string;
   parentSpanId?: string;
   traceparent?: string;
+  tracestate?: string;
+}
+
+/** Values accepted as tracing attributes. */
+export type TraceAttributeValue =
+  | string
+  | number
+  | boolean
+  | readonly string[]
+  | readonly number[]
+  | readonly boolean[];
+
+/** Attributes attached to a traced Beignet operation. */
+export type TraceAttributes = Readonly<Record<string, TraceAttributeValue>>;
+
+/** Span kinds understood by tracing providers. */
+export type TraceSpanKind =
+  | "internal"
+  | "server"
+  | "client"
+  | "producer"
+  | "consumer";
+
+/** Stable Beignet operation categories used by tracing and metrics providers. */
+export type TraceOperationType =
+  | "request"
+  | "useCase"
+  | "listener"
+  | "job"
+  | "schedule"
+  | "task"
+  | "outbox"
+  | "provider";
+
+/** Description of one operation to run inside an active trace span. */
+export interface TraceOperation {
+  name: string;
+  type: TraceOperationType;
+  kind?: TraceSpanKind;
+  parent?: TraceContextInput;
+  /** Attributes attached to the operation span. */
+  attributes?: TraceAttributes;
+  /**
+   * Bounded attributes attached to operation metrics. Values must describe a
+   * stable operation dimension, never a request, actor, tenant, or payload.
+   */
+  metricAttributes?: TraceAttributes;
+}
+
+/** Framework-neutral span handle exposed to Beignet execution wrappers. */
+export interface TraceSpan {
+  readonly context: TraceContext;
+  setAttribute(name: string, value: TraceAttributeValue): void;
+  setAttributes(attributes: TraceAttributes): void;
+  addEvent(name: string, attributes?: TraceAttributes): void;
+  setStatus(status: "ok" | "error"): void;
+  recordError(error: unknown): void;
+}
+
+/** Optional app port implemented by production tracing integrations. */
+export interface TracingPort {
+  current(): TraceContext | undefined;
+  startActiveSpan<T>(operation: TraceOperation, run: (span: TraceSpan) => T): T;
+}
+
+function isObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null;
+}
+
+/** Return whether a value implements `TracingPort`. */
+export function isTracingPort(value: unknown): value is TracingPort {
+  return (
+    isObject(value) &&
+    "current" in value &&
+    "startActiveSpan" in value &&
+    typeof value.current === "function" &&
+    typeof value.startActiveSpan === "function"
+  );
+}
+
+/** Resolve a tracing port from a direct port, ports object, or app context. */
+export function resolveTracingPort(target: unknown): TracingPort | undefined {
+  if (!target) return undefined;
+  if (isTracingPort(target)) return target;
+  if (!isObject(target)) return undefined;
+
+  const direct = "tracing" in target ? (target.tracing as unknown) : undefined;
+  if (isTracingPort(direct)) return direct;
+
+  const ports = "ports" in target ? target.ports : undefined;
+  if (!ports || ports === target) return undefined;
+  return resolveTracingPort(ports);
+}
+
+/** Resolve trace fields from a trace context or context-like object. */
+export function resolveTraceContextInput(
+  target: unknown,
+): TraceContextInput | undefined {
+  if (!isObject(target)) return undefined;
+
+  const context = target as TraceContextInput;
+  if (
+    context.traceId ||
+    context.spanId ||
+    context.parentSpanId ||
+    context.traceparent ||
+    context.tracestate
+  ) {
+    return {
+      ...(context.traceId ? { traceId: context.traceId } : {}),
+      ...(context.spanId ? { spanId: context.spanId } : {}),
+      ...(context.parentSpanId ? { parentSpanId: context.parentSpanId } : {}),
+      ...(context.traceparent ? { traceparent: context.traceparent } : {}),
+      ...(context.tracestate ? { tracestate: context.tracestate } : {}),
+    };
+  }
+
+  const traceContext = "trace" in target ? target.trace : undefined;
+  if (!traceContext || traceContext === target) return undefined;
+  return resolveTraceContextInput(traceContext);
+}
+
+/** Run a callback inside a tracing span when an app tracing port is installed. */
+export function runWithTracing<T>(
+  target: unknown,
+  operation: TraceOperation,
+  run: (span?: TraceSpan) => T,
+): T {
+  const tracing = resolveTracingPort(target);
+  if (!tracing) return run();
+  return tracing.startActiveSpan(operation, (span) => run(span));
 }
 
 function createHexId(length: number): string {
@@ -159,6 +294,7 @@ export function createTraceContext(
       spanId,
       traceFlags: parsed?.traceFlags,
     }),
+    ...(input.tracestate ? { tracestate: input.tracestate } : {}),
   };
 }
 
@@ -172,5 +308,6 @@ export function createChildTraceContext(
     traceId: parent.traceId,
     parentSpanId: parent.spanId,
     traceparent: parent.traceparent,
+    tracestate: parent.tracestate,
   });
 }

package/src/uploads/client.ts

@@ -391,6 +391,17 @@ export function createUploadClient<
     uploadName: Name,
     prepareOptions: UploadClientPrepareOptions<UploadByName<Registry, Name>>,
   ) {
+    const fileConstraints = constraints(uploadName);
+    const files = await Promise.all(
+      prepareOptions.files.map((file) =>
+        fileIntentFromFile({
+          file,
+          constraints: fileConstraints,
+          uploadName,
+        }),
+      ),
+    );
+
     return requestJson<PrepareUploadResult>({
       fetchImpl,
       url: actionUrl(baseUrl, uploadName, "prepare"),
@@ -403,7 +414,7 @@ export function createUploadClient<
         signal: prepareOptions.signal,
         body: JSON.stringify({
           metadata: prepareOptions.metadata,
-          files: prepareOptions.files.map(fileIntentFromFile),
+          files,
         }),
       },
     });
@@ -564,12 +575,28 @@ export function createUploadClient<
   };
 }
 
-function fileIntentFromFile(file: File): UploadFileIntent {
-  return {
-    name: file.name,
-    contentType: file.type || "application/octet-stream",
-    size: file.size,
+async function fileIntentFromFile(args: {
+  file: File;
+  constraints: UploadFileConstraints | undefined;
+  uploadName: string;
+}): Promise<UploadFileIntent> {
+  const contentType =
+    normalizeContentType(args.file.type) || "application/octet-stream";
+  const intent: UploadFileIntent = {
+    name: args.file.name,
+    contentType,
+    size: args.file.size,
   };
+
+  const checksumRequirement = args.constraints?.checksum;
+  if (checksumRequirement?.algorithm === "sha256") {
+    intent.checksum = await createClientUploadChecksum(args.file, {
+      uploadName: args.uploadName,
+      required: checksumRequirement.required !== false,
+    });
+  }
+
+  return intent;
 }
 
 function completeFileInput(file: PreparedUploadResultFile): PreparedUploadFile {
@@ -577,15 +604,47 @@ function completeFileInput(file: PreparedUploadResultFile): PreparedUploadFile {
     name: file.name,
     contentType: file.contentType,
     size: file.size,
+    ...(file.checksum ? { checksum: file.checksum } : {}),
     uploadId: file.uploadId,
     key: file.key,
   };
 }
 
+async function createClientUploadChecksum(
+  file: File,
+  options: { uploadName: string; required: boolean },
+): Promise<UploadFileIntent["checksum"]> {
+  if (!globalThis.crypto?.subtle) {
+    if (!options.required) return undefined;
+
+    throw new UploadClientError({
+      operation: "prepare upload",
+      uploadName: options.uploadName,
+      code: "UPLOAD_CHECKSUM_UNAVAILABLE",
+      message: `Upload "${options.uploadName}" requires Web Crypto to compute checksums.`,
+    });
+  }
+
+  const digest = await globalThis.crypto.subtle.digest(
+    "SHA-256",
+    await file.arrayBuffer(),
+  );
+  return {
+    algorithm: "sha256",
+    value: [...new Uint8Array(digest)]
+      .map((byte) => byte.toString(16).padStart(2, "0"))
+      .join(""),
+  };
+}
+
 function normalizeBaseUrl(baseUrl: string): string {
   return baseUrl.replace(/\/+$/, "");
 }
 
+function normalizeContentType(contentType: string): string {
+  return contentType.split(";")[0]?.trim().toLowerCase() ?? "";
+}
+
 function actionUrl(
   baseUrl: string,
   uploadName: string,