@gmickel/gno 1.23.0 → 1.25.1

package/src/serve/routes/clipper.ts

@@ -0,0 +1,394 @@
+/** Dedicated loopback browser-clipper HTTP gateway. */
+
+import type { HttpMcpPeerServer } from "../../mcp/http-security";
+import type { SqliteAdapter } from "../../store/sqlite/adapter";
+import type { ContextHolder } from "./api";
+
+import { prepareBrowserClip } from "../../core/browser-clip";
+import {
+  planResidentCapture,
+  type ResidentCapturePlanResult,
+} from "../capture-service";
+import { executeClipperCapture } from "../clipper-capture";
+import {
+  clipperApprovalSchema,
+  clipperBearerToken,
+  clipperErrorResponse,
+  clipperLoopbackAuthority,
+  clipperResponse,
+  clipperSha256,
+  isClipperPairId,
+} from "../clipper-contract";
+import {
+  ClipperPairingService,
+  type ClipperPairPollResult,
+} from "../clipper-pairing";
+import {
+  ClipperSecurityBoundary,
+  type ClipperAdmission,
+  withClipperCors,
+} from "../clipper-security";
+
+type ClipperRoute = (
+  request: Request,
+  server: HttpMcpPeerServer
+) => Promise<Response> | Response;
+
+export interface ClipperRouteGateway {
+  readonly routes: Record<
+    string,
+    Partial<Record<"GET" | "POST" | "OPTIONS", ClipperRoute>>
+  >;
+}
+
+interface AuthenticatedAdmission {
+  admission: ClipperAdmission;
+  grant: Extract<
+    ReturnType<ClipperPairingService["authorize"]>,
+    { status: "authorized" }
+  >["grant"];
+}
+
+const releaseWithCors = (
+  admission: ClipperAdmission,
+  result: Response
+): Response => {
+  admission.release();
+  return withClipperCors(result, admission.origin);
+};
+
+const planProjection = (
+  planned: Extract<ResidentCapturePlanResult, { ok: true }>
+): {
+  collection: string;
+  relPath: string;
+  outcome: string;
+  provenanceConflict: boolean;
+} => ({
+  collection: planned.plan.collection,
+  relPath: planned.plan.relPath,
+  outcome: planned.plan.collisionPolicyResult,
+  provenanceConflict: planned.plan.provenanceConflict,
+});
+
+const pollStatusCode = (result: ClipperPairPollResult): number => {
+  if (result.status === "not_found") return 404;
+  if (
+    result.status === "expired" ||
+    result.status === "consumed" ||
+    result.status === "origin_mismatch"
+  ) {
+    return 410;
+  }
+  return 200;
+};
+
+export function createClipperRouteGateway(
+  ctxHolder: ContextHolder,
+  store: SqliteAdapter,
+  options: { host: string; port: number }
+): ClipperRouteGateway {
+  const authority = clipperLoopbackAuthority(options.host, options.port);
+  const listenerOrigin = `http://${authority}`;
+  const security = new ClipperSecurityBoundary({
+    allowedHosts: [authority],
+    sameOrigins: [listenerOrigin],
+  });
+  const pairing = new ClipperPairingService(store.getRawDb());
+  const db = store.getRawDb();
+
+  const admitExtension = async (
+    request: Request,
+    server: HttpMcpPeerServer,
+    readJson: boolean
+  ) =>
+    security.admit(request, server, {
+      origin: { kind: "extension" },
+      readJson,
+    });
+
+  const authenticate = async (
+    request: Request,
+    server: HttpMcpPeerServer,
+    readJson: boolean
+  ): Promise<
+    | { ok: true; value: AuthenticatedAdmission }
+    | { ok: false; response: Response }
+  > => {
+    const admitted = await admitExtension(request, server, readJson);
+    if (!admitted.ok) return admitted;
+    const token = clipperBearerToken(request);
+    if (!token) {
+      return {
+        ok: false,
+        response: releaseWithCors(
+          admitted.value,
+          clipperErrorResponse("CLIPPER_UNAUTHORIZED", "Unauthorized", 401)
+        ),
+      };
+    }
+    const authorized = pairing.authorize(token, admitted.value.origin);
+    if (authorized.status !== "authorized") {
+      return {
+        ok: false,
+        response: releaseWithCors(
+          admitted.value,
+          clipperErrorResponse("CLIPPER_UNAUTHORIZED", "Unauthorized", 401)
+        ),
+      };
+    }
+    return {
+      ok: true,
+      value: { admission: admitted.value, grant: authorized.grant },
+    };
+  };
+
+  const startPair: ClipperRoute = async (request, server) => {
+    const admitted = await admitExtension(request, server, false);
+    if (!admitted.ok) return admitted.response;
+    try {
+      const started = pairing.start(admitted.value.origin);
+      return withClipperCors(
+        clipperResponse({
+          schemaVersion: "1.0",
+          ...started,
+          origin: admitted.value.origin,
+          approvalPath: "/api/clipper/pair/approve",
+        }),
+        admitted.value.origin
+      );
+    } catch (error) {
+      return withClipperCors(
+        clipperErrorResponse(
+          "CLIPPER_PAIRING_UNAVAILABLE",
+          error instanceof Error ? error.message : "Pairing unavailable",
+          429
+        ),
+        admitted.value.origin
+      );
+    } finally {
+      admitted.value.release();
+    }
+  };
+
+  const csrf: ClipperRoute = async (request, server) => {
+    const admitted = await security.admit(request, server, {
+      origin: { allowOriginlessSafeGet: true, kind: "same-origin" },
+    });
+    if (!admitted.ok) return admitted.response;
+    try {
+      return clipperResponse({
+        schemaVersion: "1.0",
+        csrfToken: pairing.csrfToken,
+      });
+    } finally {
+      admitted.value.release();
+    }
+  };
+
+  const approvePair: ClipperRoute = async (request, server) => {
+    const admitted = await security.admit(request, server, {
+      origin: { kind: "same-origin" },
+      readJson: true,
+    });
+    if (!admitted.ok) return admitted.response;
+    try {
+      if (request.headers.get("x-gno-csrf") !== pairing.csrfToken) {
+        return clipperErrorResponse("CLIPPER_CSRF", "Invalid CSRF token", 403);
+      }
+      const parsed = clipperApprovalSchema.safeParse(admitted.value.body);
+      if (!parsed.success) {
+        return clipperErrorResponse(
+          "CLIPPER_INVALID_REQUEST",
+          "Invalid pairing approval",
+          400
+        );
+      }
+      const approved = pairing.approve(
+        parsed.data.pairId,
+        parsed.data.pairingCode
+      );
+      if (approved.status !== "approved") {
+        const status = approved.status === "invalid_code" ? 403 : 410;
+        return clipperErrorResponse(
+          `CLIPPER_PAIR_${approved.status.toUpperCase()}`,
+          "Pairing could not be approved",
+          status
+        );
+      }
+      return clipperResponse({
+        schemaVersion: "1.0",
+        status: approved.status,
+        origin: approved.origin,
+        expiresAt: approved.expiresAt,
+      });
+    } finally {
+      admitted.value.release();
+    }
+  };
+
+  const pollPair: ClipperRoute = async (request, server) => {
+    const admitted = await admitExtension(request, server, false);
+    if (!admitted.ok) return admitted.response;
+    try {
+      const pairId = new URL(request.url).pathname.split("/").at(-1) ?? "";
+      if (!isClipperPairId(pairId)) {
+        return withClipperCors(
+          clipperErrorResponse(
+            "CLIPPER_PAIR_NOT_FOUND",
+            "Pairing not found",
+            404
+          ),
+          admitted.value.origin
+        );
+      }
+      const result = pairing.poll(pairId, admitted.value.origin);
+      return withClipperCors(
+        clipperResponse(
+          { schemaVersion: "1.0", ...result },
+          pollStatusCode(result)
+        ),
+        admitted.value.origin
+      );
+    } finally {
+      admitted.value.release();
+    }
+  };
+
+  const revoke: ClipperRoute = async (request, server) => {
+    const authenticated = await authenticate(request, server, false);
+    if (!authenticated.ok) return authenticated.response;
+    const { admission, grant } = authenticated.value;
+    try {
+      const revoked = pairing.revoke(grant);
+      return withClipperCors(
+        clipperResponse({
+          schemaVersion: "1.0",
+          grantId: grant.id,
+          ...revoked,
+        }),
+        admission.origin
+      );
+    } finally {
+      admission.release();
+    }
+  };
+
+  const preview: ClipperRoute = async (request, server) => {
+    const authenticated = await authenticate(request, server, true);
+    if (!authenticated.ok) return authenticated.response;
+    const { admission, grant } = authenticated.value;
+    try {
+      const prepared = prepareBrowserClip(admission.body);
+      const planned = await planResidentCapture(
+        ctxHolder,
+        store,
+        prepared.captureInput
+      );
+      if (!planned.ok) {
+        return withClipperCors(
+          clipperErrorResponse(planned.code, planned.message, planned.status),
+          admission.origin
+        );
+      }
+      const payloadDigest = clipperSha256(JSON.stringify(prepared.payload));
+      pairing.issuePreview(grant.id, prepared.preview.digest, payloadDigest);
+      return withClipperCors(
+        clipperResponse({
+          schemaVersion: "1.0",
+          preview: prepared.preview,
+          provenance: prepared.provenance,
+          plan: planProjection(planned),
+        }),
+        admission.origin
+      );
+    } catch (error) {
+      return withClipperCors(
+        clipperErrorResponse(
+          "CLIPPER_INVALID_REQUEST",
+          error instanceof Error ? error.message : "Invalid browser clip",
+          400
+        ),
+        admission.origin
+      );
+    } finally {
+      admission.release();
+    }
+  };
+
+  const capture: ClipperRoute = async (request, server) => {
+    const authenticated = await authenticate(request, server, true);
+    if (!authenticated.ok) return authenticated.response;
+    const { admission, grant } = authenticated.value;
+    try {
+      return withClipperCors(
+        await executeClipperCapture({
+          request,
+          body: admission.body,
+          grantId: grant.id,
+          db,
+          context: ctxHolder,
+          store,
+          pairing,
+        }),
+        admission.origin
+      );
+    } catch (error) {
+      return withClipperCors(
+        clipperErrorResponse(
+          "CLIPPER_CAPTURE_FAILED",
+          error instanceof Error ? error.message : "Browser capture failed",
+          500
+        ),
+        admission.origin
+      );
+    } finally {
+      admission.release();
+    }
+  };
+
+  const preflight =
+    (methods: readonly string[], headers?: readonly string[]): ClipperRoute =>
+    (request, server) =>
+      security.handlePreflight(request, server, {
+        origin: { kind: "extension" },
+        methods,
+        headers,
+      });
+
+  return {
+    routes: {
+      "/api/clipper/pair/start": {
+        POST: startPair,
+        OPTIONS: preflight(["POST"]),
+      },
+      "/api/clipper/pair/csrf": {
+        GET: csrf,
+      },
+      "/api/clipper/pair/approve": {
+        POST: approvePair,
+      },
+      "/api/clipper/pair/:pairId": {
+        OPTIONS: preflight(["POST"]),
+        POST: pollPair,
+      },
+      "/api/clipper/revoke": {
+        POST: revoke,
+        OPTIONS: preflight(["POST"], ["authorization"]),
+      },
+      "/api/capture/clip/preview": {
+        POST: preview,
+        OPTIONS: preflight(["POST"]),
+      },
+      "/api/capture/clip": {
+        POST: capture,
+        OPTIONS: preflight(["POST"]),
+      },
+    },
+  };
+}
+
+export const clipperRoutesForBind = (
+  loopback: boolean,
+  gateway: ClipperRouteGateway
+): ClipperRouteGateway["routes"] => (loopback ? gateway.routes : {});

package/src/serve/server.ts

@@ -70,6 +70,10 @@ import {
   handleVerifyConnector,
 } from "./routes/api";
 import { handleChanges, handleDiff, handleImpact } from "./routes/changes";
+import {
+  clipperRoutesForBind,
+  createClipperRouteGateway,
+} from "./routes/clipper";
 import { handleGraph, handleGraphQuery } from "./routes/graph";
 import {
   handleDocBacklinks,
@@ -104,6 +108,7 @@ export interface ServeResult {
 interface StartServerDependencies {
   startBackgroundRuntime?: typeof startBackgroundRuntime;
   createMcpHttpGateway?: typeof createMcpHttpGateway;
+  createClipperRouteGateway?: typeof createClipperRouteGateway;
   serve?: typeof Bun.serve;
   handleInstallConnector?: typeof handleInstallConnector;
   handleDocs?: typeof handleDocs;
@@ -217,6 +222,18 @@ export async function startServer(
       error: error instanceof Error ? error.message : String(error),
     };
   }
+  const hasSqliteClipperStore =
+    typeof Reflect.get(store, "getRawDb") === "function";
+  const clipperGateway = hasSqliteClipperStore
+    ? (dependencies.createClipperRouteGateway ?? createClipperRouteGateway)(
+        ctxHolder,
+        store,
+        {
+          host: gatewayConfig.host,
+          port: gatewayConfig.port,
+        }
+      )
+    : { routes: {} };
 
   // Shutdown controller for clean lifecycle
   const shutdownController = new AbortController();
@@ -247,6 +264,10 @@ export async function startServer(
       // Static routes - Bun handles HTML bundling and /_bun/* assets automatically
       routes: {
         "/mcp": gateway.route,
+        ...clipperRoutesForBind(
+          isHttpGatewayLoopbackBind(gatewayConfig.host),
+          clipperGateway
+        ),
         // SPA routes - all serve the same React app
         "/": homepage,
         "/search": homepage,
@@ -258,6 +279,7 @@ export async function startServer(
         "/traces": homepage,
         "/ask": homepage,
         "/graph": homepage,
+        "/clipper/pair": homepage,
 
         // API routes with CSRF protection wrapper
         "/api/health": {

package/src/store/migrations/020-browser-clipper-security.ts

@@ -0,0 +1,128 @@
+/**
+ * Migration: persisted browser-clipper grants and write idempotency.
+ *
+ * Pairing codes and bearer tokens never enter SQLite. Only SHA-256 token/key
+ * digests, exact extension origins, bounded grant lifetimes, and completed
+ * capture receipts are durable across resident restarts.
+ *
+ * @module src/store/migrations/020-browser-clipper-security
+ */
+
+import type { Database } from "bun:sqlite";
+
+import type { Migration } from "./runner";
+
+export const migration: Migration = {
+  version: 20,
+  name: "browser_clipper_security",
+
+  up(db: Database): void {
+    db.exec(`
+      CREATE TABLE clipper_grants (
+        id TEXT PRIMARY KEY,
+        token_hash TEXT NOT NULL UNIQUE,
+        origin TEXT NOT NULL,
+        scope TEXT NOT NULL DEFAULT 'capture'
+          CHECK (scope = 'capture'),
+        created_at_ms INTEGER NOT NULL CHECK (created_at_ms >= 0),
+        expires_at_ms INTEGER NOT NULL CHECK (expires_at_ms > created_at_ms),
+        revoked_at_ms INTEGER
+          CHECK (revoked_at_ms IS NULL OR revoked_at_ms >= created_at_ms),
+        CHECK (length(id) BETWEEN 1 AND 128),
+        CHECK (
+          length(token_hash) = 64
+          AND token_hash NOT GLOB '*[^0-9a-f]*'
+        ),
+        CHECK (
+          length(origin) = 51
+          AND substr(origin, 1, 19) = 'chrome-extension://'
+          AND substr(origin, 20) NOT GLOB '*[^a-p]*'
+        )
+      );
+
+      CREATE INDEX idx_clipper_grants_expiry
+      ON clipper_grants(expires_at_ms, id);
+
+      CREATE TABLE clipper_capture_idempotency (
+        grant_id TEXT NOT NULL,
+        key_hash TEXT NOT NULL,
+        request_digest TEXT NOT NULL,
+        collection TEXT NOT NULL,
+        rel_path TEXT NOT NULL,
+        collision_policy_result TEXT NOT NULL
+          CHECK (
+            collision_policy_result IN (
+              'created',
+              'opened_existing',
+              'created_with_suffix',
+              'overwritten',
+              'conflict'
+            )
+          ),
+        content_hash TEXT NOT NULL,
+        clip_identity TEXT NOT NULL,
+        state TEXT NOT NULL CHECK (state IN ('pending', 'completed')),
+        status_code INTEGER,
+        response_json TEXT,
+        created_at_ms INTEGER NOT NULL CHECK (created_at_ms >= 0),
+        completed_at_ms INTEGER
+          CHECK (
+            completed_at_ms IS NULL OR completed_at_ms >= created_at_ms
+          ),
+        PRIMARY KEY (grant_id, key_hash),
+        FOREIGN KEY (grant_id)
+          REFERENCES clipper_grants(id)
+          ON DELETE CASCADE,
+        CHECK (
+          length(key_hash) = 64
+          AND key_hash NOT GLOB '*[^0-9a-f]*'
+        ),
+        UNIQUE (grant_id, request_digest),
+        CHECK (
+          length(request_digest) = 64
+          AND request_digest NOT GLOB '*[^0-9a-f]*'
+        ),
+        CHECK (length(CAST(collection AS BLOB)) BETWEEN 1 AND 256),
+        CHECK (length(CAST(rel_path AS BLOB)) BETWEEN 1 AND 8192),
+        CHECK (
+          length(content_hash) = 64
+          AND content_hash NOT GLOB '*[^0-9a-f]*'
+        ),
+        CHECK (
+          length(clip_identity) = 64
+          AND clip_identity NOT GLOB '*[^0-9a-f]*'
+        ),
+        CHECK (
+          response_json IS NULL
+          OR length(CAST(response_json AS BLOB)) <= 2097152
+        ),
+        CHECK (
+          (
+            state = 'pending'
+            AND status_code IS NULL
+            AND response_json IS NULL
+            AND completed_at_ms IS NULL
+          )
+          OR
+          (
+            state = 'completed'
+            AND status_code BETWEEN 200 AND 599
+            AND response_json IS NOT NULL
+            AND json_valid(response_json)
+            AND completed_at_ms IS NOT NULL
+          )
+        )
+      );
+
+      CREATE INDEX idx_clipper_idempotency_created
+      ON clipper_capture_idempotency(created_at_ms, grant_id, key_hash);
+    `);
+  },
+
+  down(db: Database): void {
+    db.exec("DROP INDEX IF EXISTS idx_clipper_idempotency_created");
+    db.exec("DROP TABLE IF EXISTS clipper_capture_idempotency");
+    db.exec("DROP INDEX IF EXISTS idx_clipper_grants_expiry");
+    db.exec("DROP TABLE IF EXISTS clipper_grants");
+  },
+};

package/src/store/migrations/index.ts

@@ -33,6 +33,7 @@ import { migration as m016 } from "./016-saved-capsules";
 import { migration as m017 } from "./017-document-change-retention-counters";
 import { migration as m018 } from "./018-saved-capsule-registration-epoch";
 import { migration as m019 } from "./019-saved-capsule-registration-generation";
+import { migration as m020 } from "./020-browser-clipper-security";
 
 /** All migrations in order */
 export const migrations = [
@@ -55,4 +56,5 @@ export const migrations = [
   m017,
   m018,
   m019,
+  m020,
 ];

package/src/store/sqlite/clipper-store-types.ts

@@ -0,0 +1,104 @@
+/** Public contracts for browser-clipper SQLite persistence. */
+
+export interface ClipperGrantInput {
+  id: string;
+  tokenHash: string;
+  origin: string;
+  createdAtMs: number;
+  expiresAtMs: number;
+}
+
+export interface ClipperGrant {
+  id: string;
+  origin: string;
+  scope: "capture";
+  createdAtMs: number;
+  expiresAtMs: number;
+  revokedAtMs: number | null;
+}
+
+export type CreateClipperGrantResult =
+  | { status: "created"; grant: ClipperGrant }
+  | { status: "duplicate"; grant: ClipperGrant }
+  | { status: "conflict" };
+
+export type AuthorizeClipperGrantResult =
+  | { status: "authorized"; grant: ClipperGrant }
+  | { status: "unauthorized" }
+  | { status: "expired" }
+  | { status: "revoked" };
+
+export type RevokeClipperGrantResult =
+  | { status: "revoked"; grant: ClipperGrant }
+  | { status: "already_revoked"; grant: ClipperGrant }
+  | { status: "expired"; grant: ClipperGrant }
+  | { status: "not_found" };
+
+export type ClipperCollisionPolicyResult =
+  | "created"
+  | "opened_existing"
+  | "created_with_suffix"
+  | "overwritten"
+  | "conflict";
+
+export interface ClipperIdempotencyPlan {
+  collection: string;
+  relPath: string;
+  collisionPolicyResult: ClipperCollisionPolicyResult;
+  contentHash: string;
+  clipIdentity: string;
+}
+
+export interface ClaimClipperIdempotencyInput {
+  grantId: string;
+  keyHash: string;
+  requestDigest: string;
+  plan: ClipperIdempotencyPlan;
+  nowMs: number;
+}
+
+export interface CompleteClipperIdempotencyInput {
+  grantId: string;
+  keyHash: string;
+  requestDigest: string;
+  responseJson: string;
+  statusCode: number;
+  nowMs: number;
+}
+
+export interface InspectClipperIdempotencyInput {
+  grantId: string;
+  keyHash: string;
+  requestDigest: string;
+}
+
+export interface ClipperIdempotencyPending {
+  requestDigest: string;
+  plan: ClipperIdempotencyPlan;
+  createdAtMs: number;
+}
+
+export interface ClipperIdempotencyReplay extends ClipperIdempotencyPending {
+  statusCode: number;
+  responseJson: string;
+  completedAtMs: number;
+}
+
+export type ClaimClipperIdempotencyResult =
+  | { status: "claimed" }
+  | { status: "pending"; pending: ClipperIdempotencyPending }
+  | { status: "replay"; replay: ClipperIdempotencyReplay }
+  | { status: "conflict" }
+  | { status: "grant_inactive" };
+
+export type InspectClipperIdempotencyResult =
+  | { status: "pending"; pending: ClipperIdempotencyPending }
+  | { status: "replay"; replay: ClipperIdempotencyReplay }
+  | { status: "conflict" }
+  | { status: "not_found" };
+
+export type CompleteClipperIdempotencyResult =
+  | { status: "completed"; replay: ClipperIdempotencyReplay }
+  | { status: "replay"; replay: ClipperIdempotencyReplay }
+  | { status: "conflict" }
+  | { status: "not_found" };