@gmickel/gno 1.24.0 → 1.26.0

package/src/serve/clipper-capture.ts

@@ -0,0 +1,248 @@
+/** Browser-clipper write orchestration and crash-safe idempotency recovery. */
+
+import type { Database } from "bun:sqlite";
+
+import type { PreparedBrowserClip } from "../core/browser-clip";
+import type { SqliteAdapter } from "../store/sqlite/adapter";
+import type { ClipperIdempotencyReplay } from "../store/sqlite/clipper-store-types";
+import type { ResidentCaptureContext } from "./capture-service";
+import type { ClipperPairingService } from "./clipper-pairing";
+
+import { prepareBrowserClip } from "../core/browser-clip";
+import {
+  claimClipperIdempotency,
+  inspectClipperIdempotency,
+} from "../store/sqlite/clipper-store";
+import {
+  browserClipIdempotencyPlan,
+  executeResidentCapturePlan,
+  planResidentCapture,
+  recoverPendingResidentBrowserClip,
+} from "./capture-service";
+import {
+  clipperCaptureWriteSchema,
+  clipperErrorResponse,
+  clipperSha256,
+  isClipperIdempotencyKey,
+} from "./clipper-contract";
+import { completeClipperHttpIdempotency } from "./clipper-idempotency";
+
+interface ExecuteClipperCaptureInput {
+  request: Request;
+  body: unknown;
+  grantId: string;
+  db: Database;
+  context: ResidentCaptureContext;
+  store: SqliteAdapter;
+  pairing: ClipperPairingService;
+}
+
+const inFlightRequests = new Set<string>();
+
+const inFlightKey = (grantId: string, requestDigest: string): string =>
+  `${grantId}\0${requestDigest}`;
+
+const pendingResponse = (): Response =>
+  clipperErrorResponse(
+    "CLIPPER_IDEMPOTENCY_PENDING",
+    "The matching browser capture is still in progress",
+    409
+  );
+
+const replayResponse = (replay: ClipperIdempotencyReplay): Response =>
+  new Response(replay.responseJson, {
+    status: replay.statusCode,
+    headers: {
+      "Content-Type": "application/json",
+      "Idempotent-Replay": "true",
+    },
+  });
+
+const completeResponse = (
+  input: ExecuteClipperCaptureInput,
+  keyHash: string,
+  requestDigest: string,
+  body: unknown,
+  status: number
+): Response =>
+  completeClipperHttpIdempotency(input.db, {
+    grantId: input.grantId,
+    keyHash,
+    requestDigest,
+    body:
+      body !== null && typeof body === "object" && !Array.isArray(body)
+        ? { schemaVersion: "1.0", ...body }
+        : body,
+    status,
+  });
+
+const executeAndComplete = async (
+  input: ExecuteClipperCaptureInput,
+  keyHash: string,
+  requestDigest: string,
+  planned: Parameters<typeof executeResidentCapturePlan>[2]
+): Promise<Response> => {
+  const result = await executeResidentCapturePlan(
+    input.context,
+    input.store,
+    planned
+  );
+  return completeResponse(
+    input,
+    keyHash,
+    requestDigest,
+    result.body,
+    result.status
+  );
+};
+
+const recoverPending = async (
+  input: ExecuteClipperCaptureInput,
+  prepared: PreparedBrowserClip,
+  keyHash: string,
+  requestDigest: string,
+  plan: Parameters<typeof recoverPendingResidentBrowserClip>[3]
+): Promise<Response> => {
+  const activeKey = inFlightKey(input.grantId, requestDigest);
+  if (inFlightRequests.has(activeKey)) return pendingResponse();
+  inFlightRequests.add(activeKey);
+  try {
+    const recovered = await recoverPendingResidentBrowserClip(
+      input.context,
+      input.store,
+      prepared,
+      plan
+    );
+    if (recovered.status === "conflict") {
+      return clipperErrorResponse(
+        "CLIPPER_IDEMPOTENCY_RECOVERY_CONFLICT",
+        recovered.message,
+        409
+      );
+    }
+    if (recovered.status === "execute") {
+      return executeAndComplete(
+        input,
+        keyHash,
+        requestDigest,
+        recovered.planned
+      );
+    }
+    return completeResponse(
+      input,
+      keyHash,
+      requestDigest,
+      recovered.body,
+      recovered.statusCode
+    );
+  } finally {
+    inFlightRequests.delete(activeKey);
+  }
+};
+
+export const executeClipperCapture = async (
+  input: ExecuteClipperCaptureInput
+): Promise<Response> => {
+  const parsed = clipperCaptureWriteSchema.safeParse(input.body);
+  const idempotencyKey = input.request.headers.get("idempotency-key") ?? "";
+  if (!parsed.success || !isClipperIdempotencyKey(idempotencyKey)) {
+    return clipperErrorResponse(
+      "CLIPPER_INVALID_REQUEST",
+      "A valid preview and Idempotency-Key are required",
+      400
+    );
+  }
+
+  const prepared = prepareBrowserClip(parsed.data.payload);
+  if (prepared.preview.digest !== parsed.data.previewDigest) {
+    return clipperErrorResponse(
+      "CLIPPER_PREVIEW_MISMATCH",
+      "Browser clip changed after preview",
+      409
+    );
+  }
+
+  const payloadDigest = clipperSha256(JSON.stringify(prepared.payload));
+  const requestDigest = clipperSha256(
+    `${parsed.data.previewDigest}\0${payloadDigest}`
+  );
+  const keyHash = clipperSha256(idempotencyKey);
+  const inspected = inspectClipperIdempotency(input.db, {
+    grantId: input.grantId,
+    keyHash,
+    requestDigest,
+  });
+  if (inspected.status === "replay") {
+    return replayResponse(inspected.replay);
+  }
+  if (inspected.status === "conflict") {
+    return clipperErrorResponse(
+      "CLIPPER_IDEMPOTENCY_CONFLICT",
+      "Idempotency key was used for a different browser capture",
+      409
+    );
+  }
+  if (inspected.status === "pending") {
+    return recoverPending(
+      input,
+      prepared,
+      keyHash,
+      requestDigest,
+      inspected.pending.plan
+    );
+  }
+
+  if (
+    input.pairing.verifyPreview(
+      input.grantId,
+      parsed.data.previewDigest,
+      payloadDigest
+    ) !== "matched"
+  ) {
+    return clipperErrorResponse(
+      "CLIPPER_PREVIEW_REQUIRED",
+      "Create a fresh matching preview before capture",
+      409
+    );
+  }
+
+  const planned = await planResidentCapture(
+    input.context,
+    input.store,
+    prepared.captureInput
+  );
+  if (!planned.ok) {
+    return clipperErrorResponse(planned.code, planned.message, planned.status);
+  }
+  const claim = claimClipperIdempotency(input.db, {
+    grantId: input.grantId,
+    keyHash,
+    requestDigest,
+    plan: browserClipIdempotencyPlan(planned),
+    nowMs: Date.now(),
+  });
+  if (claim.status === "replay") return replayResponse(claim.replay);
+  if (claim.status === "pending") {
+    return recoverPending(
+      input,
+      prepared,
+      keyHash,
+      requestDigest,
+      claim.pending.plan
+    );
+  }
+  if (claim.status !== "claimed") {
+    return clipperErrorResponse(
+      `CLIPPER_IDEMPOTENCY_${claim.status.toUpperCase()}`,
+      "Idempotency key cannot be claimed",
+      409
+    );
+  }
+  const activeKey = inFlightKey(input.grantId, requestDigest);
+  inFlightRequests.add(activeKey);
+  try {
+    return await executeAndComplete(input, keyHash, requestDigest, planned);
+  } finally {
+    inFlightRequests.delete(activeKey);
+  }
+};

package/src/serve/clipper-contract.ts

@@ -0,0 +1,57 @@
+/** Closed request parsing and stable responses for browser-clipper routes. */
+
+import { z } from "zod";
+
+const PAIR_ID_PATTERN = /^[a-f0-9]{64}$/u;
+const IDEMPOTENCY_KEY_PATTERN = /^[\x21-\x7e]{1,256}$/u;
+
+export const clipperApprovalSchema = z
+  .object({
+    pairId: z.string().regex(PAIR_ID_PATTERN),
+    pairingCode: z.string().regex(/^\d{8}$/u),
+  })
+  .strict();
+
+export const clipperCaptureWriteSchema = z
+  .object({
+    payload: z.unknown(),
+    previewDigest: z.string().regex(/^[a-f0-9]{64}$/u),
+  })
+  .strict();
+
+export const isClipperPairId = (value: string): boolean =>
+  PAIR_ID_PATTERN.test(value);
+
+export const isClipperIdempotencyKey = (value: string): boolean =>
+  IDEMPOTENCY_KEY_PATTERN.test(value);
+
+export const clipperLoopbackAuthority = (
+  host: string,
+  port: number
+): string => {
+  const authorityHost = host === "::1" || host === "[::1]" ? "[::1]" : host;
+  return `${authorityHost}:${port}`;
+};
+
+export const clipperBearerToken = (request: Request): string | null =>
+  request.headers
+    .get("authorization")
+    ?.match(/^Bearer (?<token>[a-f0-9]{64})$/u)?.groups?.token ?? null;
+
+export const clipperSha256 = (value: string): string =>
+  new Bun.CryptoHasher("sha256").update(value).digest("hex");
+
+export const clipperResponse = (body: unknown, status = 200): Response =>
+  Response.json(body, {
+    status,
+    headers: {
+      "Cache-Control": "no-store",
+      "X-Content-Type-Options": "nosniff",
+    },
+  });
+
+export const clipperErrorResponse = (
+  code: string,
+  message: string,
+  status: number
+): Response => clipperResponse({ error: { code, message } }, status);

package/src/serve/clipper-idempotency.ts

@@ -0,0 +1,35 @@
+/** HTTP receipt persistence for browser-clipper idempotent writes. */
+
+import type { Database } from "bun:sqlite";
+
+import { completeClipperIdempotency } from "../store/sqlite/clipper-store";
+
+export const completeClipperHttpIdempotency = (
+  db: Database,
+  input: {
+    grantId: string;
+    keyHash: string;
+    requestDigest: string;
+    body: unknown;
+    status: number;
+  }
+): Response => {
+  const responseJson = JSON.stringify(input.body);
+  const completed = completeClipperIdempotency(db, {
+    grantId: input.grantId,
+    keyHash: input.keyHash,
+    requestDigest: input.requestDigest,
+    responseJson,
+    statusCode: input.status,
+    nowMs: Date.now(),
+  });
+  if (completed.status === "conflict" || completed.status === "not_found") {
+    throw new Error(
+      `Browser clip idempotency completion failed: ${completed.status}`
+    );
+  }
+  return new Response(responseJson, {
+    status: input.status,
+    headers: { "Content-Type": "application/json" },
+  });
+};

package/src/serve/clipper-pairing.ts

@@ -0,0 +1,297 @@
+/** In-memory pairing and preview state for the loopback browser clipper. */
+
+import type { Database } from "bun:sqlite";
+
+import type {
+  AuthorizeClipperGrantResult,
+  ClipperGrant,
+} from "../store/sqlite/clipper-store";
+
+import {
+  authorizeClipperGrant,
+  createClipperGrant,
+  revokeClipperGrant,
+} from "../store/sqlite/clipper-store";
+
+const EXTENSION_ORIGIN_PATTERN = /^chrome-extension:\/\/[a-p]{32}$/u;
+const PAIR_TTL_MS = 5 * 60 * 1000;
+const GRANT_TTL_MS = 30 * 24 * 60 * 60 * 1000;
+const PREVIEW_TTL_MS = 5 * 60 * 1000;
+const MAX_PENDING_PAIRS = 128;
+const MAX_PREVIEWS = 512;
+const MAX_APPROVAL_ATTEMPTS = 5;
+
+interface PendingPair {
+  approvalAttempts: number;
+  codeHash: string;
+  expiresAtMs: number;
+  origin: string;
+  state: "pending" | "approved" | "consumed";
+  grant?: {
+    id: string;
+    token: string;
+    expiresAtMs: number;
+  };
+}
+
+interface IssuedPreview {
+  expiresAtMs: number;
+  payloadDigest: string;
+}
+
+export interface ClipperPairingOptions {
+  now?: () => number;
+  randomBytes?: (length: number) => Uint8Array;
+  pairTtlMs?: number;
+  grantTtlMs?: number;
+  previewTtlMs?: number;
+}
+
+export type ClipperPairPollResult =
+  | { status: "pending"; expiresAt: string }
+  | {
+      status: "approved";
+      grantId: string;
+      grantToken: string;
+      expiresAt: string;
+    }
+  | { status: "consumed" }
+  | { status: "expired" }
+  | { status: "not_found" }
+  | { status: "origin_mismatch" };
+
+const sha256 = (value: string): string =>
+  new Bun.CryptoHasher("sha256").update(value).digest("hex");
+
+const randomHex = (
+  length: number,
+  randomBytes: (length: number) => Uint8Array
+): string =>
+  [...randomBytes(length)]
+    .map((byte) => byte.toString(16).padStart(2, "0"))
+    .join("");
+
+const defaultRandomBytes = (length: number): Uint8Array =>
+  crypto.getRandomValues(new Uint8Array(length));
+
+const constantTimeEqual = (left: string, right: string): boolean => {
+  if (left.length !== right.length) return false;
+  let difference = 0;
+  for (let index = 0; index < left.length; index += 1) {
+    difference |= left.charCodeAt(index) ^ right.charCodeAt(index);
+  }
+  return difference === 0;
+};
+
+const pairCode = (randomBytes: (length: number) => Uint8Array): string => {
+  const bytes = randomBytes(4);
+  const value =
+    (((bytes[0] ?? 0) << 24) |
+      ((bytes[1] ?? 0) << 16) |
+      ((bytes[2] ?? 0) << 8) |
+      (bytes[3] ?? 0)) >>>
+    0;
+  return String(value % 100_000_000).padStart(8, "0");
+};
+
+export const isClipperExtensionOrigin = (origin: string): boolean =>
+  EXTENSION_ORIGIN_PATTERN.test(origin);
+
+export class ClipperPairingService {
+  readonly #db: Database;
+  readonly #now: () => number;
+  readonly #randomBytes: (length: number) => Uint8Array;
+  readonly #pairTtlMs: number;
+  readonly #grantTtlMs: number;
+  readonly #previewTtlMs: number;
+  readonly #pairs = new Map<string, PendingPair>();
+  readonly #previews = new Map<string, IssuedPreview>();
+  readonly #csrfToken: string;
+
+  constructor(db: Database, options: ClipperPairingOptions = {}) {
+    this.#db = db;
+    this.#now = options.now ?? Date.now;
+    this.#randomBytes = options.randomBytes ?? defaultRandomBytes;
+    this.#pairTtlMs = options.pairTtlMs ?? PAIR_TTL_MS;
+    this.#grantTtlMs = options.grantTtlMs ?? GRANT_TTL_MS;
+    this.#previewTtlMs = options.previewTtlMs ?? PREVIEW_TTL_MS;
+    this.#csrfToken = randomHex(32, this.#randomBytes);
+  }
+
+  get csrfToken(): string {
+    return this.#csrfToken;
+  }
+
+  start(origin: string): {
+    pairId: string;
+    pairingCode: string;
+    expiresAt: string;
+  } {
+    if (!isClipperExtensionOrigin(origin)) {
+      throw new TypeError("Invalid browser extension origin");
+    }
+    this.#prune();
+    if (this.#pairs.size >= MAX_PENDING_PAIRS) {
+      throw new Error("Too many pending browser clipper pairings");
+    }
+    const pairId = randomHex(32, this.#randomBytes);
+    const code = pairCode(this.#randomBytes);
+    const expiresAtMs = this.#now() + this.#pairTtlMs;
+    this.#pairs.set(pairId, {
+      approvalAttempts: 0,
+      codeHash: sha256(`${pairId}\0${origin}\0${code}`),
+      expiresAtMs,
+      origin,
+      state: "pending",
+    });
+    return {
+      pairId,
+      pairingCode: code,
+      expiresAt: new Date(expiresAtMs).toISOString(),
+    };
+  }
+
+  approve(
+    pairId: string,
+    pairingCode: string
+  ):
+    | { status: "approved"; origin: string; expiresAt: string }
+    | { status: "not_found" | "expired" | "invalid_code" | "already_used" } {
+    const pair = this.#pairs.get(pairId);
+    if (!pair) return { status: "not_found" };
+    const nowMs = this.#now();
+    if (nowMs >= pair.expiresAtMs) {
+      this.#pairs.delete(pairId);
+      return { status: "expired" };
+    }
+    if (pair.state !== "pending") return { status: "already_used" };
+    pair.approvalAttempts += 1;
+    const candidate = sha256(`${pairId}\0${pair.origin}\0${pairingCode}`);
+    if (!constantTimeEqual(candidate, pair.codeHash)) {
+      if (pair.approvalAttempts >= MAX_APPROVAL_ATTEMPTS) {
+        this.#pairs.delete(pairId);
+      }
+      return { status: "invalid_code" };
+    }
+
+    const grantId = crypto.randomUUID();
+    const token = randomHex(32, this.#randomBytes);
+    const expiresAtMs = nowMs + this.#grantTtlMs;
+    const created = createClipperGrant(this.#db, {
+      id: grantId,
+      tokenHash: sha256(token),
+      origin: pair.origin,
+      createdAtMs: nowMs,
+      expiresAtMs,
+    });
+    if (created.status !== "created") {
+      throw new Error("Failed to create browser clipper grant");
+    }
+    pair.state = "approved";
+    pair.grant = { id: grantId, token, expiresAtMs };
+    return {
+      status: "approved",
+      origin: pair.origin,
+      expiresAt: new Date(expiresAtMs).toISOString(),
+    };
+  }
+
+  poll(pairId: string, origin: string): ClipperPairPollResult {
+    const pair = this.#pairs.get(pairId);
+    if (!pair) return { status: "not_found" };
+    if (pair.origin !== origin) return { status: "origin_mismatch" };
+    const nowMs = this.#now();
+    if (nowMs >= pair.expiresAtMs) {
+      this.#pairs.delete(pairId);
+      return { status: "expired" };
+    }
+    if (pair.state === "pending") {
+      return {
+        status: "pending",
+        expiresAt: new Date(pair.expiresAtMs).toISOString(),
+      };
+    }
+    if (pair.state === "consumed" || !pair.grant) {
+      return { status: "consumed" };
+    }
+    const grant = pair.grant;
+    pair.state = "consumed";
+    pair.grant = undefined;
+    return {
+      status: "approved",
+      grantId: grant.id,
+      grantToken: grant.token,
+      expiresAt: new Date(grant.expiresAtMs).toISOString(),
+    };
+  }
+
+  authorize(token: string, origin: string): AuthorizeClipperGrantResult {
+    return authorizeClipperGrant(this.#db, sha256(token), origin, this.#now());
+  }
+
+  revoke(
+    grant: ClipperGrant
+  ):
+    | { status: "revoked"; revokedAt: string }
+    | { status: "already_revoked" | "expired" | "not_found" } {
+    const result = revokeClipperGrant(this.#db, grant.id, this.#now());
+    if (result.status !== "revoked") return { status: result.status };
+    return {
+      status: "revoked",
+      revokedAt: new Date(
+        result.grant.revokedAtMs ?? this.#now()
+      ).toISOString(),
+    };
+  }
+
+  issuePreview(
+    grantId: string,
+    previewDigest: string,
+    payloadDigest: string
+  ): void {
+    this.#prune();
+    if (this.#previews.size >= MAX_PREVIEWS) {
+      const oldest = this.#previews.keys().next().value;
+      if (oldest !== undefined) this.#previews.delete(oldest);
+    }
+    this.#previews.set(`${grantId}:${previewDigest}`, {
+      expiresAtMs: this.#now() + this.#previewTtlMs,
+      payloadDigest,
+    });
+  }
+
+  consumePreview(
+    grantId: string,
+    previewDigest: string,
+    payloadDigest: string
+  ): "matched" | "missing" | "expired" | "mismatch" {
+    const key = `${grantId}:${previewDigest}`;
+    const preview = this.#previews.get(key);
+    if (!preview) return "missing";
+    this.#previews.delete(key);
+    if (this.#now() >= preview.expiresAtMs) return "expired";
+    return preview.payloadDigest === payloadDigest ? "matched" : "mismatch";
+  }
+
+  verifyPreview(
+    grantId: string,
+    previewDigest: string,
+    payloadDigest: string
+  ): "matched" | "missing" | "expired" | "mismatch" {
+    const preview = this.#previews.get(`${grantId}:${previewDigest}`);
+    if (!preview) return "missing";
+    if (this.#now() >= preview.expiresAtMs) return "expired";
+    return preview.payloadDigest === payloadDigest ? "matched" : "mismatch";
+  }
+
+  #prune(): void {
+    const nowMs = this.#now();
+    for (const [id, pair] of this.#pairs) {
+      if (nowMs < pair.expiresAtMs) continue;
+      this.#pairs.delete(id);
+    }
+    for (const [key, preview] of this.#previews) {
+      if (nowMs >= preview.expiresAtMs) this.#previews.delete(key);
+    }
+  }
+}

package/src/serve/clipper-security-errors.ts

@@ -0,0 +1,23 @@
+/** Stable closed failures for the browser-clipper transport boundary. */
+
+const SECURITY_ERRORS = {
+  CLIPPER_ABORTED: { message: "Clipper request aborted", status: 503 },
+  CLIPPER_BODY_TOO_LARGE: {
+    message: "Clipper request body too large",
+    status: 413,
+  },
+  CLIPPER_BUSY: { message: "Clipper request queue is full", status: 429 },
+  CLIPPER_FORBIDDEN: { message: "Forbidden", status: 403 },
+  CLIPPER_INVALID_JSON: { message: "Invalid JSON body", status: 400 },
+  CLIPPER_RATE_LIMITED: { message: "Too many clipper requests", status: 429 },
+} as const;
+
+export function clipperSecurityErrorResponse(
+  code: keyof typeof SECURITY_ERRORS
+): Response {
+  const detail = SECURITY_ERRORS[code];
+  return Response.json(
+    { error: { code, message: detail.message } },
+    { status: detail.status }
+  );
+}