@serovaai/ficta-contract 0.0.0

package/package.json

@@ -0,0 +1,63 @@
+{
+  "name": "@serovaai/ficta-contract",
+  "version": "0.0.0",
+  "private": false,
+  "description": "Typed oRPC and OpenAPI contract for the Ficta control plane",
+  "homepage": "https://ficta.sh",
+  "bugs": {
+    "url": "https://github.com/SerovaAI/ficta/issues"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/SerovaAI/ficta.git",
+    "directory": "packages/contract"
+  },
+  "files": [
+    "dist/",
+    "openapi/",
+    "src/",
+    "README.md",
+    "LICENSE"
+  ],
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "development": "./src/index.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./openapi.json": "./openapi/ficta-control-plane.openapi.json"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@orpc/client": "1.15.0",
+    "@orpc/contract": "1.15.0",
+    "@orpc/openapi-client": "1.15.0",
+    "@serovaai/ficta-protocol": "^0.2.3",
+    "zod": "^4.5.4"
+  },
+  "devDependencies": {
+    "@orpc/openapi": "1.15.0",
+    "@orpc/zod": "1.15.0",
+    "@types/node": "^26.4.1",
+    "oxfmt": "^0.66.0",
+    "typescript": "^7.0.2",
+    "vitest": "^4.1.11"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "pnpm build:dist && node scripts/generate-openapi.mjs",
+    "build:dist": "tsc",
+    "check": "pnpm check:static && pnpm typecheck && pnpm test && pnpm check:openapi",
+    "check:openapi": "pnpm build:dist && node scripts/generate-openapi.mjs --check",
+    "check:static": "oxlint . && oxfmt --check .",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
+  }
+}

package/src/client.ts

@@ -0,0 +1,29 @@
+import { createORPCClient } from "@orpc/client";
+import type { ContractRouterClient } from "@orpc/contract";
+import type { JsonifiedClient } from "@orpc/openapi-client";
+import { OpenAPILink } from "@orpc/openapi-client/fetch";
+import { fictaControlContract } from "./contract.js";
+import { decodeFictaControlError } from "./errors.js";
+
+export type FictaControlClient = JsonifiedClient<ContractRouterClient<typeof fictaControlContract>>;
+
+export interface CreateFictaControlClientOptions {
+  baseUrl: string | URL;
+  headers?: Headers | Record<string, string>;
+  fetch?: typeof globalThis.fetch;
+}
+
+/** Create a fetch-based client for any conforming Ficta control-plane implementation. */
+export function createFictaControlClient(options: CreateFictaControlClientOptions): FictaControlClient {
+  const link = new OpenAPILink(fictaControlContract, {
+    url: options.baseUrl,
+    headers: options.headers,
+    customErrorResponseBodyDecoder: decodeFictaControlError,
+    ...(options.fetch
+      ? {
+          fetch: (request, init) => options.fetch?.(request, init) ?? globalThis.fetch(request, init),
+        }
+      : {}),
+  });
+  return createORPCClient<FictaControlClient>(link);
+}

package/src/contract.ts

@@ -0,0 +1,60 @@
+import { FICTA_HEALTH_PATH, FICTA_PROTECTION_PREVIEW_PATH, FICTA_STATUS_PATH } from "@serovaai/ficta-protocol";
+import { oc } from "@orpc/contract";
+import {
+  capabilitiesSchema,
+  FICTA_CAPABILITIES_PATH,
+  healthSchema,
+  protectionPreviewDetectorUnavailableErrorSchema,
+  protectionPreviewForbiddenErrorSchema,
+  protectionPreviewInputSchema,
+  protectionPreviewInvalidRequestErrorSchema,
+  protectionPreviewInvariantErrorSchema,
+  protectionPreviewSchema,
+  protectionStatusSchema,
+} from "./schemas.js";
+
+const controlProcedure = oc;
+
+export const fictaControlContract = oc.tag("Ficta control plane").router({
+  capabilities: controlProcedure
+    .route({
+      method: "GET",
+      path: FICTA_CAPABILITIES_PATH,
+      operationId: "getFictaCapabilities",
+      summary: "Discover the Ficta control-plane version and supported procedures",
+    })
+    .output(capabilitiesSchema),
+  health: controlProcedure
+    .route({
+      method: "GET",
+      path: FICTA_HEALTH_PATH,
+      operationId: "getFictaHealth",
+      summary: "Check whether the Ficta proxy process is serving requests",
+    })
+    .output(healthSchema),
+  status: controlProcedure
+    .route({
+      method: "GET",
+      path: FICTA_STATUS_PATH,
+      operationId: "getFictaProtectionStatus",
+      summary: "Read values-free protection readiness and activity metadata",
+    })
+    .output(protectionStatusSchema),
+  protectionPreview: controlProcedure
+    .route({
+      method: "POST",
+      path: FICTA_PROTECTION_PREVIEW_PATH,
+      operationId: "createFictaProtectionPreview",
+      summary: "Preview protection and issue a short-lived send ticket",
+    })
+    .input(protectionPreviewInputSchema)
+    .output(protectionPreviewSchema)
+    .errors({
+      FORBIDDEN: { status: 403, data: protectionPreviewForbiddenErrorSchema },
+      INVALID_REQUEST: { status: 400, data: protectionPreviewInvalidRequestErrorSchema },
+      DETECTOR_UNAVAILABLE: { status: 503, data: protectionPreviewDetectorUnavailableErrorSchema },
+      INVARIANT: { status: 422, data: protectionPreviewInvariantErrorSchema },
+    }),
+});
+
+export type FictaControlContract = typeof fictaControlContract;

package/src/errors.ts

@@ -0,0 +1,76 @@
+import { ORPCError } from "@orpc/client";
+import { protectionPreviewErrorSchema, type FictaProtectionPreviewError } from "./schemas.js";
+
+const previewErrorCodes = {
+  forbidden: "FORBIDDEN",
+  invalid_request: "INVALID_REQUEST",
+  detector_unavailable: "DETECTOR_UNAVAILABLE",
+  invariant: "INVARIANT",
+} as const;
+
+/** Encode defined preview errors with the stable pre-oRPC HTTP response body. */
+export function encodeFictaControlError(error: ORPCError<string, unknown>): unknown {
+  const parsed = protectionPreviewErrorSchema.safeParse(error.data);
+  if (parsed.success) return parsed.data;
+  if (error.code === "BAD_REQUEST") {
+    return {
+      ok: false,
+      service: "ficta",
+      status: "invalid_request",
+      message: protectionPreviewValidationMessage(error.data),
+    } satisfies FictaProtectionPreviewError;
+  }
+  return undefined;
+}
+
+function protectionPreviewValidationMessage(data: unknown): string {
+  if (!data || typeof data !== "object" || !("issues" in data) || !Array.isArray(data.issues)) {
+    return "Invalid protection preview request.";
+  }
+  const issue = data.issues[0];
+  if (!issue || typeof issue !== "object") return "Invalid protection preview request.";
+  const record = issue as { code?: unknown; message?: unknown; path?: unknown };
+  const path = Array.isArray(record.path) ? record.path : [];
+  if (path.length === 0) return "Preview body must be an object.";
+  if (path[0] === "text") {
+    return record.code === "too_big" || record.message === "Preview text is too large."
+      ? "Preview text is too large."
+      : "Preview text is required.";
+  }
+  if (path[0] === "protectedValues") {
+    if (path.length === 1) {
+      if (record.code === "too_big") return "Too many protected values for one chat.";
+      if (record.message === "Protected values are too large for one chat.") return record.message;
+      return "Protected values must be a list.";
+    }
+    return record.code === "invalid_type"
+      ? "Every protected value must be text."
+      : "A protected value is empty or too long.";
+  }
+  return "Invalid protection preview request.";
+}
+
+/** Decode the stable HTTP error body back into the contract's typed oRPC error. */
+export function decodeFictaControlError(
+  body: unknown,
+  response: { status: number },
+): ORPCError<string, unknown> | undefined {
+  const parsed = protectionPreviewErrorSchema.safeParse(body);
+  if (!parsed.success) return undefined;
+  return new ORPCError(previewErrorCodes[parsed.data.status], {
+    defined: true,
+    status: response.status,
+    message: parsed.data.message,
+    data: parsed.data,
+  });
+}
+
+export function fictaControlErrorStatus(error: unknown): number | undefined {
+  return error instanceof ORPCError ? error.status : undefined;
+}
+
+export function fictaControlErrorData(error: unknown): FictaProtectionPreviewError | undefined {
+  if (!(error instanceof ORPCError)) return undefined;
+  const parsed = protectionPreviewErrorSchema.safeParse(error.data);
+  return parsed.success ? parsed.data : undefined;
+}

package/src/index.ts

@@ -0,0 +1,43 @@
+export {
+  FICTA_HEALTH_PATH,
+  FICTA_PROTECTION_PREVIEW_PATH,
+  FICTA_PROTECTION_TICKET_HEADER,
+  FICTA_SCOPE_HEADER,
+  FICTA_STATUS_PATH,
+} from "@serovaai/ficta-protocol";
+export { createFictaControlClient, type CreateFictaControlClientOptions, type FictaControlClient } from "./client.js";
+export { fictaControlContract, type FictaControlContract } from "./contract.js";
+export {
+  decodeFictaControlError,
+  encodeFictaControlError,
+  fictaControlErrorData,
+  fictaControlErrorStatus,
+} from "./errors.js";
+export {
+  capabilitiesSchema,
+  FICTA_CAPABILITIES_PATH,
+  FICTA_CONTROL_CAPABILITIES,
+  FICTA_CONTROL_PROTOCOL_VERSION,
+  FICTA_SCOPE_MAX_LENGTH,
+  healthSchema,
+  PROTECTION_PREVIEW_TEXT_MAX_BYTES,
+  PROTECTION_PREVIEW_VALUE_MAX,
+  PROTECTION_PREVIEW_VALUES_MAX,
+  PROTECTION_PREVIEW_VALUES_MAX_BYTES,
+  protectionPreviewDetectorUnavailableErrorSchema,
+  protectionPreviewErrorSchema,
+  protectionPreviewFindingSchema,
+  protectionPreviewForbiddenErrorSchema,
+  protectionPreviewInputSchema,
+  protectionPreviewInvalidRequestErrorSchema,
+  protectionPreviewInvariantErrorSchema,
+  protectionPreviewSchema,
+  protectionStatusSchema,
+  registryProtectionStatusSchema,
+  type FictaCapabilities,
+  type FictaHealth,
+  type FictaProtectionPreview,
+  type FictaProtectionPreviewError,
+  type FictaProtectionPreviewInput,
+  type FictaProtectionStatus,
+} from "./schemas.js";

package/src/schemas.ts

@@ -0,0 +1,202 @@
+import { z } from "zod";
+
+export const FICTA_CAPABILITIES_PATH = "/__ficta/capabilities" as const;
+export const FICTA_CONTROL_PROTOCOL_VERSION = 1 as const;
+export const FICTA_CONTROL_CAPABILITIES = ["health", "status", "protection-preview"] as const;
+export const FICTA_SCOPE_MAX_LENGTH = 256;
+
+export const PROTECTION_PREVIEW_TEXT_MAX_BYTES = 2 * 1024 * 1024;
+export const PROTECTION_PREVIEW_VALUES_MAX = 200;
+export const PROTECTION_PREVIEW_VALUE_MAX = 2_000;
+export const PROTECTION_PREVIEW_VALUES_MAX_BYTES = 64 * 1024;
+
+const utf8Length = (value: string): number => new TextEncoder().encode(value).byteLength;
+
+export const healthSchema = z
+  .object({
+    ok: z.literal(true),
+    service: z.literal("ficta"),
+  })
+  .strict();
+
+export const capabilitiesSchema = z
+  .object({
+    ok: z.literal(true),
+    service: z.literal("ficta"),
+    protocolVersion: z
+      .literal(FICTA_CONTROL_PROTOCOL_VERSION)
+      .describe("Breaking wire-contract version implemented by this control plane."),
+    capabilities: z
+      .array(z.string().min(1))
+      .describe("Supported optional procedures. Clients must ignore capability names they do not recognize."),
+  })
+  .strict();
+
+export const registryProtectionStatusSchema = z
+  .object({
+    required: z.boolean().describe("Whether provider requests are blocked until the registry is ready."),
+    status: z.enum(["ready", "empty", "error"]).describe("Current exact-match registry readiness."),
+    message: z.string().describe("Values-free operator guidance for the current registry state."),
+  })
+  .strict();
+
+export const protectionStatusSchema = z
+  .object({
+    ok: z.literal(true),
+    service: z.literal("ficta"),
+    protection: z
+      .object({
+        enabled: z.boolean().describe("Whether the engine has registered values or detector plugins available."),
+        protecting: z.boolean().describe("Whether registered values or an active detector are currently configured."),
+        registeredValues: z.number().int().nonnegative().describe("Count of loaded exact-match protected values."),
+        policyExcluded: z
+          .number()
+          .int()
+          .nonnegative()
+          .describe("Count of discovered registry values excluded by configured policy."),
+      })
+      .strict(),
+    registry: registryProtectionStatusSchema.optional(),
+    secretShapes: z
+      .object({
+        enabled: z.boolean().describe("Whether request-time secret-shape detection is enabled."),
+        status: z.enum(["off", "ok"]).describe("Secret-shape detector posture."),
+        message: z.string().describe("Values-free explanation of the secret-shape posture."),
+      })
+      .strict(),
+    pii: z
+      .object({
+        enabled: z.boolean().describe("Whether request-time PII detection is enabled."),
+        configuredBackend: z.string().describe("Compatibility string naming the configured PII backend set."),
+        configuredBackends: z.array(z.string()).optional().describe("Configured PII backend names."),
+        backend: z.string().describe("Active PII backend names as a compatibility string."),
+        status: z.enum(["off", "ok", "degraded", "blocking"]).describe("Current PII detector posture."),
+        failureMode: z
+          .enum(["fail-open", "fail-closed"])
+          .describe("Whether a required PII backend outage skips that backend or blocks provider traffic."),
+        url: z.string().optional().describe("Values-free health URL for a single configured network backend."),
+        detail: z.string().optional().describe("Values-free backend health diagnostic."),
+        message: z.string().describe("Values-free explanation of the current PII posture."),
+      })
+      .strict(),
+    activity: z
+      .object({
+        restoredValues: z
+          .number()
+          .int()
+          .nonnegative()
+          .describe("Cumulative protected values restored during this proxy run."),
+        withheldFromTools: z
+          .number()
+          .int()
+          .nonnegative()
+          .describe("Cumulative protected values withheld from tool-call arguments during this proxy run."),
+      })
+      .strict()
+      .optional(),
+  })
+  .strict();
+
+export const protectionHitSchema = z
+  .object({
+    name: z.string().describe("Values-free detector or registry label for the finding."),
+    source: z.string().describe("Values-free source category for the finding."),
+    plugin: z.string().optional().describe("Plugin that produced the finding, when available."),
+    kind: z.enum(["secret", "pii", "custom"]).optional().describe("Coarse protected-value category."),
+    confidence: z
+      .enum(["exact", "high", "probabilistic"])
+      .optional()
+      .describe("Confidence class assigned by the protection source."),
+  })
+  .strict();
+
+export const protectionPreviewFindingSchema = protectionHitSchema.extend({
+  start: z.number().int().nonnegative().describe("Inclusive UTF-16 offset into the exact preview text."),
+  end: z.number().int().nonnegative().describe("Exclusive UTF-16 offset into the exact preview text."),
+  surrogate: z.string().describe("Opaque replacement rendered in redactedText."),
+  origin: z.enum(["registry", "detected", "user"]).describe("How this protected value entered the preview."),
+});
+
+const protectedValueSchema = z
+  .string()
+  .min(1)
+  .max(PROTECTION_PREVIEW_VALUE_MAX)
+  .transform((value) => value.trim())
+  .refine((value) => value.length > 0 && value.length <= PROTECTION_PREVIEW_VALUE_MAX, {
+    message: "A protected value is empty or too long.",
+  });
+
+export const protectionPreviewTextSchema = z
+  .string()
+  .max(PROTECTION_PREVIEW_TEXT_MAX_BYTES)
+  .refine((value) => utf8Length(value) <= PROTECTION_PREVIEW_TEXT_MAX_BYTES, {
+    message: "Preview text is too large.",
+  });
+
+export const protectionPreviewProtectedValuesSchema = z
+  .array(protectedValueSchema)
+  .max(PROTECTION_PREVIEW_VALUES_MAX)
+  .optional();
+
+export const protectionPreviewInputSchema = z
+  .object({
+    text: protectionPreviewTextSchema,
+    protectedValues: protectionPreviewProtectedValuesSchema,
+  })
+  .transform(({ text, protectedValues = [] }, context) => {
+    const uniqueValues = [...new Set(protectedValues)];
+    const valuesBytes = uniqueValues.reduce((total, value) => total + utf8Length(value), 0);
+    if (valuesBytes > PROTECTION_PREVIEW_VALUES_MAX_BYTES) {
+      context.addIssue({ code: "custom", message: "Protected values are too large for one chat." });
+      return z.NEVER;
+    }
+    return { text, protectedValues: uniqueValues };
+  });
+
+export const protectionPreviewSchema = z
+  .object({
+    ok: z.literal(true),
+    service: z.literal("ficta"),
+    ticket: z.string().describe("Opaque, short-lived, single-use authorization for the reviewed provider send."),
+    textSha256: z
+      .string()
+      .regex(/^[0-9a-f]{64}$/u)
+      .describe("Lowercase SHA-256 of the exact preview text bound to the ticket."),
+    redactedText: z.string().describe("Preview text with all planned protections applied."),
+    findings: z.array(protectionPreviewFindingSchema).describe("Ordered protected occurrences in the preview text."),
+  })
+  .strict();
+
+const protectionPreviewErrorBaseSchema = z
+  .object({
+    ok: z.literal(false),
+    service: z.literal("ficta"),
+    message: z.string(),
+  })
+  .strict();
+
+export const protectionPreviewForbiddenErrorSchema = protectionPreviewErrorBaseSchema.extend({
+  status: z.literal("forbidden"),
+});
+export const protectionPreviewInvalidRequestErrorSchema = protectionPreviewErrorBaseSchema.extend({
+  status: z.literal("invalid_request"),
+});
+export const protectionPreviewDetectorUnavailableErrorSchema = protectionPreviewErrorBaseSchema.extend({
+  status: z.literal("detector_unavailable"),
+});
+export const protectionPreviewInvariantErrorSchema = protectionPreviewErrorBaseSchema.extend({
+  status: z.literal("invariant"),
+});
+export const protectionPreviewErrorSchema = z.discriminatedUnion("status", [
+  protectionPreviewForbiddenErrorSchema,
+  protectionPreviewInvalidRequestErrorSchema,
+  protectionPreviewDetectorUnavailableErrorSchema,
+  protectionPreviewInvariantErrorSchema,
+]);
+
+export type FictaCapabilities = z.output<typeof capabilitiesSchema>;
+export type FictaHealth = z.output<typeof healthSchema>;
+export type FictaProtectionStatus = z.output<typeof protectionStatusSchema>;
+export type FictaProtectionPreviewInput = z.input<typeof protectionPreviewInputSchema>;
+export type FictaProtectionPreview = z.output<typeof protectionPreviewSchema>;
+export type FictaProtectionPreviewError = z.output<typeof protectionPreviewErrorSchema>;