@neutrome/platform-contracts 0.1.0

package/package.json

@@ -0,0 +1,20 @@
+{
+  "name": "@neutrome/platform-contracts",
+  "version": "0.1.0",
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "dependencies": {
+    "jose": "^6.2.0",
+    "zod": "^4.4.3"
+  },
+  "devDependencies": {
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.6"
+  },
+  "scripts": {
+    "test": "vitest run",
+    "typecheck": "tsc -p tsconfig.json --noEmit"
+  }
+}

package/src/auth.ts

@@ -0,0 +1,24 @@
+import { z } from "zod";
+
+const nonEmptyString = z.string().min(1);
+
+export const PlatformSessionSchema = z
+  .object({
+    user: z
+      .object({
+        id: nonEmptyString,
+        email: nonEmptyString,
+        name: z.string().nullable().optional(),
+      })
+      .passthrough(),
+    session: z
+      .object({
+        id: nonEmptyString.optional(),
+        expiresAt: nonEmptyString.optional(),
+      })
+      .passthrough()
+      .nullable(),
+  })
+  .passthrough();
+
+export type PlatformSession = z.infer<typeof PlatformSessionSchema>;

package/src/billing-trace.test.ts

@@ -0,0 +1,51 @@
+import { describe, expect, it } from "vitest";
+import { BillingExecutionTraceSchema } from "./billing-trace.ts";
+
+const trace = {
+  spanId: "span-1",
+  startedAt: "2026-07-12T12:00:00.000Z",
+  spans: [
+    {
+      kind: "provider",
+      event: "provider.finished",
+      requestId: "request-1",
+      executionId: "provider-1",
+      startedAt: "2026-07-12T12:00:00.000Z",
+      tokensInput: 10,
+      tokensOutput: 20,
+      cachedTokensInput: 2,
+      requestBytes: 100,
+      responseBytes: 200,
+    },
+  ],
+  totalTokensInput: 10,
+  totalTokensOutput: 20,
+  totalCachedTokensInput: 2,
+};
+
+describe("BillingExecutionTrace", () => {
+  it("accepts complete router trace data", () => {
+    expect(BillingExecutionTraceSchema.safeParse(trace).data).toEqual(trace);
+  });
+
+  it("rejects malformed spans and negative counters", () => {
+    expect(
+      BillingExecutionTraceSchema.safeParse({
+        ...trace,
+        spans: [{ ...trace.spans[0], kind: "other" }],
+      }).success,
+    ).toBe(false);
+    expect(
+      BillingExecutionTraceSchema.safeParse({
+        ...trace,
+        spans: [{ ...trace.spans[0], tokensOutput: -1 }],
+      }).success,
+    ).toBe(false);
+    expect(
+      BillingExecutionTraceSchema.safeParse({
+        ...trace,
+        totalTokensInput: "10",
+      }).success,
+    ).toBe(false);
+  });
+});

package/src/billing-trace.ts

@@ -0,0 +1,42 @@
+import { z } from "zod";
+
+const counter = z.number().finite().nonnegative();
+const optionalText = z.string().min(1).optional();
+
+export const BillingTraceSpanSchema = z.object({
+  kind: z.enum(["request", "provider", "tool", "executor"]),
+  event: z.string().min(1),
+  requestId: z.string().min(1),
+  executionId: z.string().min(1),
+  parentExecutionId: optionalText,
+  model: optionalText,
+  provider: optionalText,
+  toolName: optionalText,
+  executor: optionalText,
+  startedAt: z.string().min(1),
+  finishedAt: optionalText,
+  tokensInput: counter,
+  tokensOutput: counter,
+  cachedTokensInput: counter,
+  requestBytes: counter,
+  responseBytes: counter,
+  error: optionalText,
+});
+
+export const BillingExecutionTraceSchema = z.object({
+  spanId: z.string().min(1),
+  startedAt: z.string().min(1),
+  finishedAt: optionalText,
+  spans: z.array(BillingTraceSpanSchema),
+  totalTokensInput: counter,
+  totalTokensOutput: counter,
+  totalCachedTokensInput: counter,
+  error: optionalText,
+});
+export const BillingTraceRequestSchema = z.object({
+  workspaceId: z.string().min(1),
+  trace: BillingExecutionTraceSchema,
+});
+
+export type BillingTraceSpan = z.infer<typeof BillingTraceSpanSchema>;
+export type BillingExecutionTrace = z.infer<typeof BillingExecutionTraceSchema>;

package/src/catalog.ts

@@ -0,0 +1,71 @@
+import { z } from "zod";
+
+const modelPattern = z
+  .string()
+  .trim()
+  .regex(/^[^/]+(?:\/[^/]+)+$/, "Expected a slash-separated model path");
+const cost = z.number().finite().int().nonnegative();
+const sourceExtension = z.enum([".js", ".ts"]);
+const galleryKind = z.enum(["model", "tool", "transform"]);
+
+export const CreateModelPricingRequestSchema = z.object({
+  modelPattern,
+  inputCostMicrosPerM: cost,
+  outputCostMicrosPerM: cost,
+  cachedInputCostMicrosPerM: cost,
+});
+export const UpdateModelPricingRequestSchema =
+  CreateModelPricingRequestSchema.partial()
+    .refine((input) => Object.keys(input).length > 0)
+    .transform((input) => ({
+      ...(input.modelPattern === undefined
+        ? {}
+        : { modelPattern: input.modelPattern }),
+      ...(input.inputCostMicrosPerM === undefined
+        ? {}
+        : { inputCostMicrosPerM: input.inputCostMicrosPerM }),
+      ...(input.outputCostMicrosPerM === undefined
+        ? {}
+        : { outputCostMicrosPerM: input.outputCostMicrosPerM }),
+      ...(input.cachedInputCostMicrosPerM === undefined
+        ? {}
+        : { cachedInputCostMicrosPerM: input.cachedInputCostMicrosPerM }),
+    }));
+
+export const TemplateGalleryKindSchema = galleryKind;
+export const CreateTemplateGalleryRequestSchema = z.object({
+  kind: galleryKind,
+  name: z.string().trim().min(1),
+  description: z.string().trim(),
+  sourceCode: z.string().min(1),
+  sourceExtension,
+});
+export const UpdateTemplateGalleryRequestSchema =
+  CreateTemplateGalleryRequestSchema.partial()
+    .refine((input) => Object.keys(input).length > 0)
+    .transform((input) => ({
+      ...(input.kind === undefined ? {} : { kind: input.kind }),
+      ...(input.name === undefined ? {} : { name: input.name }),
+      ...(input.description === undefined
+        ? {}
+        : { description: input.description }),
+      ...(input.sourceCode === undefined
+        ? {}
+        : { sourceCode: input.sourceCode }),
+      ...(input.sourceExtension === undefined
+        ? {}
+        : { sourceExtension: input.sourceExtension }),
+    }));
+
+export type CreateModelPricingRequest = z.infer<
+  typeof CreateModelPricingRequestSchema
+>;
+export type UpdateModelPricingRequest = z.infer<
+  typeof UpdateModelPricingRequestSchema
+>;
+export type CreateTemplateGalleryRequest = z.infer<
+  typeof CreateTemplateGalleryRequestSchema
+>;
+export type UpdateTemplateGalleryRequest = z.infer<
+  typeof UpdateTemplateGalleryRequestSchema
+>;

package/src/index.ts

@@ -0,0 +1,164 @@
+export { PlatformSessionSchema } from "./auth.ts";
+export type { PlatformSession } from "./auth.ts";
+export {
+  createRuntimeJwtIssuer,
+  createRuntimeJwtAuthenticator,
+  RUNTIME_JWT_AUDIENCE,
+  RUNTIME_JWT_ISSUER,
+  RuntimeJwtClaimsSchema,
+  RuntimeJwtIssueInputSchema,
+  verifyRuntimeJwt,
+} from "./runtime-jwt.ts";
+export type {
+  RuntimeJwtClaims,
+  RuntimeJwtAuthenticator,
+  RuntimeJwtAuthConfig,
+  RuntimeJwtIssueInput,
+  RuntimeJwtIssuer,
+  RuntimeJwtVerificationConfig,
+} from "./runtime-jwt.ts";
+export {
+  BillingExecutionTraceSchema,
+  BillingTraceRequestSchema,
+  BillingTraceSpanSchema,
+} from "./billing-trace.ts";
+export type {
+  BillingExecutionTrace,
+  BillingTraceSpan,
+} from "./billing-trace.ts";
+export {
+  CreateWorkspaceInputSchema,
+  UpdateWorkspaceInputSchema,
+} from "./workspace.ts";
+export type {
+  CreateWorkspaceInput,
+  UpdateWorkspaceInput,
+} from "./workspace.ts";
+export {
+  CreateProviderNamespaceInputSchema,
+  UpdateProviderNamespaceInputSchema,
+} from "./namespace.ts";
+export type {
+  CreateProviderNamespaceInput,
+  UpdateProviderNamespaceInput,
+} from "./namespace.ts";
+export {
+  CreateModelRequestSchema,
+  CreateRemoteToolRequestSchema,
+  CreateToolRequestSchema,
+  CreateTransformRequestSchema,
+  RemoteMcpToolSnapshotSchema,
+  UpdateModelRequestSchema,
+  UpdateRemoteToolRequestSchema,
+  UpdateToolRequestSchema,
+  UpdateTransformRequestSchema,
+  UpsertModelSourceRequestSchema,
+} from "./resources.ts";
+export {
+  BalanceCheckSchema,
+  BillingLogSchema,
+  BillingSummarySchema,
+  BillingTransactionSchema,
+  CreatePlatformApiKeyResultSchema,
+  CheckoutSessionSchema,
+  DeployStatusSchema,
+  EmptyResponseSchema,
+  ModelPricingSchema,
+  ModelSchema,
+  OpenAiDeviceAuthStartSchema,
+  OpenAiDevicePollSchema,
+  PlatformApiKeySchema,
+  ProviderNamespaceSchema,
+  RemoteToolSchema,
+  TemplateGalleryPageSchema,
+  TemplateGallerySchema,
+  ToolSchema,
+  TransformSchema,
+  TriggerDeployResultSchema,
+  UpstreamProviderSchema,
+  WorkspaceCustomDomainSchema,
+  WorkspaceSchema,
+  WorkspaceStatsSchema,
+  WorkspacePermissionsSchema,
+} from "./records.ts";
+export type {
+  BillingLog,
+  BillingLogRecord,
+  BillingSummary,
+  BalanceCheckResult,
+  BillingTransaction,
+  BillingTransactionRecord,
+  CreatePlatformApiKeyResult,
+  DeployStatus,
+  Model,
+  ModelPricingRecord,
+  ModelRecord,
+  ModelPricing,
+  OpenAiDeviceAuthStart,
+  OpenAiDevicePoll,
+  PlatformApiKey,
+  PlatformApiKeyRecord,
+  ProviderNamespace,
+  ProviderNamespaceRecord,
+  RemoteTool,
+  RemoteToolRecord,
+  TemplateGallery,
+  TemplateGalleryKind,
+  TemplateGalleryPage,
+  TemplateGalleryRecord,
+  Tool,
+  ToolRecord,
+  TriggerDeployResult,
+  Transform,
+  TransformRecord,
+  UpstreamProvider,
+  UpstreamProviderRecord,
+  Workspace,
+  WorkspacePermissions,
+  WorkspaceRecord,
+  WorkspaceCustomDomainRecord,
+  ModelSourceExtension,
+  ModelStatus,
+  WorkspaceStats,
+} from "./records.ts";
+export {
+  CheckoutRequestSchema,
+  CreateApiKeyRequestSchema,
+  CreateUpstreamProviderRequestSchema,
+  CustomDomainRequestSchema,
+  OpenAiDevicePollRequestSchema,
+  OpenAiRefreshRequestSchema,
+  UpdateApiKeyRequestSchema,
+  UpdateUpstreamProviderRequestSchema,
+} from "./management.ts";
+export {
+  CreateModelPricingRequestSchema,
+  CreateTemplateGalleryRequestSchema,
+  TemplateGalleryKindSchema,
+  UpdateModelPricingRequestSchema,
+  UpdateTemplateGalleryRequestSchema,
+} from "./catalog.ts";
+export type {
+  CreateModelPricingRequest,
+  CreateTemplateGalleryRequest,
+  UpdateModelPricingRequest,
+  UpdateTemplateGalleryRequest,
+} from "./catalog.ts";
+export type {
+  CreateApiKeyRequest,
+  CreateUpstreamProviderRequest,
+  UpdateApiKeyRequest,
+  UpdateUpstreamProviderRequest,
+} from "./management.ts";
+export type {
+  CreateModelRequest,
+  CreateRemoteToolRequest,
+  CreateToolRequest,
+  CreateTransformRequest,
+  RemoteMcpToolSnapshot,
+  UpdateModelRequest,
+  UpdateRemoteToolRequest,
+  UpdateToolRequest,
+  UpdateTransformRequest,
+  UpsertModelSourceRequest,
+} from "./resources.ts";

package/src/management.ts

@@ -0,0 +1,98 @@
+import { z } from "zod";
+
+const nonEmptyString = z.string().min(1);
+const nullableText = z.string().nullable();
+
+export const CustomDomainRequestSchema = z.object({ hostname: nonEmptyString });
+
+export const CreateApiKeyRequestSchema = z
+  .object({
+    displayName: nonEmptyString,
+    allowedModels: z.array(nonEmptyString).optional(),
+    allowedNamespaces: z.array(nonEmptyString).optional(),
+    expiresAt: z.string().optional(),
+    isDefault: z.boolean().optional(),
+  })
+  .transform((input) => ({
+    displayName: input.displayName,
+    ...(input.allowedModels === undefined
+      ? {}
+      : { allowedModels: input.allowedModels }),
+    ...(input.allowedNamespaces === undefined
+      ? {}
+      : { allowedNamespaces: input.allowedNamespaces }),
+    ...(input.expiresAt === undefined ? {} : { expiresAt: input.expiresAt }),
+    ...(input.isDefault === undefined ? {} : { isDefault: input.isDefault }),
+  }));
+export const UpdateApiKeyRequestSchema = z
+  .object({ displayName: nonEmptyString })
+  .partial()
+  .refine((input) => Object.keys(input).length > 0)
+  .transform((input) =>
+    input.displayName === undefined ? {} : { displayName: input.displayName },
+  );
+
+const upstreamProviderFields = z.object({
+  displayName: nonEmptyString,
+  apiBaseUrl: nullableText.optional(),
+  style: nullableText.optional(),
+  apiKey: nullableText.optional(),
+  oauthAccessKey: nullableText.optional(),
+  oauthRefreshToken: nullableText.optional(),
+  oauthExpiresAt: nullableText.optional(),
+});
+const partialUpstreamProviderFields = upstreamProviderFields.partial();
+const upstreamProviderOutput = (
+  input: z.input<typeof partialUpstreamProviderFields>,
+) => ({
+  ...(input.displayName === undefined
+    ? {}
+    : { displayName: input.displayName }),
+  ...(input.apiBaseUrl === undefined ? {} : { apiBaseUrl: input.apiBaseUrl }),
+  ...(input.style === undefined ? {} : { style: input.style }),
+  ...(input.apiKey === undefined ? {} : { apiKey: input.apiKey }),
+  ...(input.oauthAccessKey === undefined
+    ? {}
+    : { oauthAccessKey: input.oauthAccessKey }),
+  ...(input.oauthRefreshToken === undefined
+    ? {}
+    : { oauthRefreshToken: input.oauthRefreshToken }),
+  ...(input.oauthExpiresAt === undefined
+    ? {}
+    : { oauthExpiresAt: input.oauthExpiresAt }),
+});
+
+export const CreateUpstreamProviderRequestSchema = upstreamProviderFields
+  .extend({
+    type: z.enum(["oauth_openai", "byok"]),
+  })
+  .transform((input) => ({
+    ...upstreamProviderOutput(input),
+    type: input.type,
+    displayName: input.displayName,
+  }));
+export const UpdateUpstreamProviderRequestSchema = partialUpstreamProviderFields
+  .refine((input) => Object.keys(input).length > 0)
+  .transform(upstreamProviderOutput);
+
+export const OpenAiDevicePollRequestSchema = z.object({
+  deviceAuthId: nonEmptyString,
+  userCode: nonEmptyString,
+});
+export const OpenAiRefreshRequestSchema = z.object({
+  providerId: nonEmptyString,
+});
+export const CheckoutRequestSchema = z.object({
+  amountCents: z.number().finite().int().positive(),
+  successUrl: z.string().url(),
+  cancelUrl: z.string().url(),
+});
+
+export type CreateApiKeyRequest = z.infer<typeof CreateApiKeyRequestSchema>;
+export type UpdateApiKeyRequest = z.infer<typeof UpdateApiKeyRequestSchema>;
+export type CreateUpstreamProviderRequest = z.infer<
+  typeof CreateUpstreamProviderRequestSchema
+>;
+export type UpdateUpstreamProviderRequest = z.infer<
+  typeof UpdateUpstreamProviderRequestSchema
+>;

package/src/namespace.ts

@@ -0,0 +1,17 @@
+import { z } from "zod";
+
+export const CreateProviderNamespaceInputSchema = z.object({
+  code: z.string().min(1),
+});
+export const UpdateProviderNamespaceInputSchema =
+  CreateProviderNamespaceInputSchema.partial()
+    .refine((input) => Object.keys(input).length > 0)
+    .transform((input): { code?: string } =>
+      input.code === undefined ? {} : { code: input.code },
+    );
+export type CreateProviderNamespaceInput = z.infer<
+  typeof CreateProviderNamespaceInputSchema
+>;
+export type UpdateProviderNamespaceInput = z.infer<
+  typeof UpdateProviderNamespaceInputSchema
+>;

package/src/records.ts

@@ -0,0 +1,297 @@
+import { z } from "zod";
+import { RemoteMcpToolSnapshotSchema } from "./resources.ts";
+
+const identifier = z.string().min(1);
+const timestamp = z.string().min(1);
+const sourceExtension = z.enum([".js", ".ts"]);
+const nullableText = z.string().nullable();
+
+export const EmptyResponseSchema = z.null().transform(() => undefined);
+
+export const WorkspaceCustomDomainSchema = z.object({
+  workspaceId: identifier,
+  hostname: identifier,
+  customHostnameId: identifier,
+  workerRouteId: nullableText,
+  status: z.string(),
+  sslStatus: nullableText,
+  verificationErrors: z.array(z.string()),
+  cnameTarget: z.string(),
+  ownershipTxtName: nullableText,
+  ownershipTxtValue: nullableText,
+  createdAt: timestamp,
+  updatedAt: timestamp,
+  lastCheckedAt: nullableText,
+});
+
+export const WorkspaceSchema = z.object({
+  id: identifier,
+  code: identifier,
+  displayName: identifier,
+  deployedUrl: nullableText,
+  generatedUrl: nullableText,
+  deployedAt: nullableText,
+  deployVersion: z.number().int(),
+  runtimeBindingsVersion: z.number().int(),
+  workerName: nullableText,
+  workerTag: nullableText,
+  repoConnectionUuid: nullableText,
+  buildTriggerUuid: nullableText,
+  customDomain: WorkspaceCustomDomainSchema.nullable(),
+  createdAt: timestamp,
+  updatedAt: timestamp,
+});
+
+export const ProviderNamespaceSchema = z.object({
+  id: identifier,
+  workspaceId: identifier,
+  code: identifier,
+  createdAt: timestamp,
+  updatedAt: timestamp,
+});
+
+export const ModelSchema = z.object({
+  id: identifier,
+  workspaceId: identifier,
+  providerNamespaceId: identifier,
+  providerNamespaceCode: identifier,
+  code: identifier,
+  sourceCode: z.string(),
+  sourceExtension,
+  status: z.enum(["draft", "deployed", "disabled"]),
+  deployedVersion: z.number().int(),
+  createdAt: timestamp,
+  updatedAt: timestamp,
+});
+
+export const ToolSchema = z.object({
+  id: identifier,
+  workspaceId: identifier,
+  displayName: identifier,
+  sourceCode: z.string(),
+  sourceExtension,
+  attachedModelIds: z.array(identifier),
+  deployedVersion: z.number().int(),
+  createdAt: timestamp,
+  updatedAt: timestamp,
+});
+
+export const TransformSchema = z.object({
+  id: identifier,
+  workspaceId: identifier,
+  code: identifier,
+  sourceCode: z.string(),
+  sourceExtension,
+  deployedVersion: z.number().int(),
+  createdAt: timestamp,
+  updatedAt: timestamp,
+});
+
+export const RemoteToolSchema = z.object({
+  id: identifier,
+  workspaceId: identifier,
+  code: identifier,
+  displayName: identifier,
+  type: z.literal("mcp_streamable_http"),
+  endpointUrl: z.string(),
+  staticHeaders: z.record(z.string(), z.string()),
+  oauthMode: z.literal("none"),
+  attachedModelIds: z.array(identifier),
+  discoveredTools: z.array(RemoteMcpToolSnapshotSchema),
+  lastRefreshedAt: nullableText,
+  lastRefreshError: nullableText,
+  deployedVersion: z.number().int(),
+  createdAt: timestamp,
+  updatedAt: timestamp,
+});
+
+export const PlatformApiKeySchema = z.object({
+  id: identifier,
+  workspaceId: identifier,
+  displayName: identifier,
+  allowedModels: z.array(identifier),
+  allowedNamespaces: z.array(identifier),
+  expiresAt: timestamp,
+  revokedAt: nullableText,
+  isDefault: z.boolean(),
+  createdAt: timestamp,
+  updatedAt: timestamp,
+});
+
+export const CreatePlatformApiKeyResultSchema = z.object({
+  key: PlatformApiKeySchema,
+  token: identifier,
+});
+
+export const WorkspaceStatsSchema = z.object({
+  namespaces: z.number().int().nonnegative(),
+  models: z.number().int().nonnegative(),
+  tools: z.number().int().nonnegative(),
+  transforms: z.number().int().nonnegative(),
+  remoteTools: z.number().int().nonnegative(),
+  apiKeys: z.number().int().nonnegative(),
+});
+
+export const WorkspacePermissionsSchema = z.object({
+  templateGalleryWrite: z.boolean(),
+  pricingWrite: z.boolean(),
+});
+
+export const TriggerDeployResultSchema = z.object({
+  workerName: identifier,
+  url: z.string().url(),
+  commitSha: identifier,
+});
+
+export const DeployStatusSchema = z.object({
+  status: z.enum([
+    "queued",
+    "initializing",
+    "building",
+    "success",
+    "failure",
+    "canceled",
+  ]),
+  url: nullableText,
+  buildUuid: nullableText,
+});
+
+export const CheckoutSessionSchema = z.object({
+  sessionId: identifier,
+  url: z.string().url(),
+});
+
+export const BillingLogSchema = z.object({
+  id: identifier,
+  workspaceId: identifier,
+  spanId: identifier,
+  providerCalls: z.number().int(),
+  toolCalls: z.number().int(),
+  tokensInput: z.number().int(),
+  tokensOutput: z.number().int(),
+  costMicros: z.number().int(),
+  errorMessage: nullableText,
+  createdAt: timestamp,
+});
+
+export const BillingSummarySchema = z.object({
+  totalRequests: z.number().int(),
+  totalTokensInput: z.number().int(),
+  totalTokensOutput: z.number().int(),
+  totalCostMicros: z.number().int(),
+});
+
+export const BillingTransactionSchema = z.object({
+  id: identifier,
+  workspaceId: identifier,
+  amountMicros: z.number().int(),
+  type: z.string(),
+  referenceId: nullableText,
+  description: nullableText,
+  createdAt: timestamp,
+});
+
+export const BalanceCheckSchema = z.object({
+  allowed: z.boolean(),
+  balanceMicros: z.number().int(),
+});
+
+export const ModelPricingSchema = z.object({
+  id: identifier,
+  modelPattern: identifier,
+  inputCostMicrosPerM: z.number().int(),
+  outputCostMicrosPerM: z.number().int(),
+  cachedInputCostMicrosPerM: z.number().int(),
+  createdAt: timestamp,
+  updatedAt: timestamp,
+});
+
+export const TemplateGallerySchema = z.object({
+  id: identifier,
+  kind: z.enum(["model", "tool", "transform"]),
+  name: identifier,
+  description: z.string(),
+  sourceCode: z.string(),
+  sourceExtension,
+  sortOrder: z.number().int(),
+  isEnabled: z.boolean(),
+  createdAt: timestamp,
+  updatedAt: timestamp,
+});
+
+export const TemplateGalleryPageSchema = z.object({
+  items: z.array(TemplateGallerySchema),
+  hasMore: z.boolean(),
+  nextOffset: z.number().int().nullable(),
+});
+
+export const UpstreamProviderSchema = z.object({
+  id: identifier,
+  workspaceId: identifier,
+  code: identifier,
+  displayName: identifier,
+  type: z.enum(["oauth_openai", "byok"]),
+  apiBaseUrl: nullableText,
+  style: nullableText,
+  apiKey: nullableText,
+  oauthAccessKey: nullableText,
+  oauthRefreshToken: nullableText,
+  oauthExpiresAt: nullableText,
+  createdAt: timestamp,
+  updatedAt: timestamp,
+});
+
+export const OpenAiDeviceAuthStartSchema = z.object({
+  deviceAuthId: identifier,
+  userCode: identifier,
+  verificationUrl: z.string().url(),
+  interval: z.number().int().positive(),
+});
+
+export const OpenAiDevicePollSchema = z.discriminatedUnion("status", [
+  z.object({ status: z.literal("pending") }),
+  z.object({ status: z.literal("complete"), provider: UpstreamProviderSchema }),
+]);
+
+export type Workspace = z.infer<typeof WorkspaceSchema>;
+export type WorkspaceRecord = Workspace;
+export type WorkspaceCustomDomainRecord = z.infer<
+  typeof WorkspaceCustomDomainSchema
+>;
+export type ModelSourceExtension = z.infer<typeof sourceExtension>;
+export type ModelStatus = z.infer<typeof ModelSchema>["status"];
+export type ProviderNamespaceRecord = z.infer<typeof ProviderNamespaceSchema>;
+export type ModelRecord = z.infer<typeof ModelSchema>;
+export type ToolRecord = z.infer<typeof ToolSchema>;
+export type TransformRecord = z.infer<typeof TransformSchema>;
+export type RemoteToolRecord = z.infer<typeof RemoteToolSchema>;
+export type PlatformApiKeyRecord = z.infer<typeof PlatformApiKeySchema>;
+export type CreatePlatformApiKeyResult = z.infer<
+  typeof CreatePlatformApiKeyResultSchema
+>;
+export type WorkspaceStats = z.infer<typeof WorkspaceStatsSchema>;
+export type WorkspacePermissions = z.infer<typeof WorkspacePermissionsSchema>;
+export type ModelPricingRecord = z.infer<typeof ModelPricingSchema>;
+export type TemplateGalleryRecord = z.infer<typeof TemplateGallerySchema>;
+export type TemplateGalleryPage = z.infer<typeof TemplateGalleryPageSchema>;
+export type TemplateGalleryKind = TemplateGalleryRecord["kind"];
+export type TriggerDeployResult = z.infer<typeof TriggerDeployResultSchema>;
+export type DeployStatus = z.infer<typeof DeployStatusSchema>;
+export type OpenAiDeviceAuthStart = z.infer<typeof OpenAiDeviceAuthStartSchema>;
+export type OpenAiDevicePoll = z.infer<typeof OpenAiDevicePollSchema>;
+export type ProviderNamespace = z.infer<typeof ProviderNamespaceSchema>;
+export type Model = z.infer<typeof ModelSchema>;
+export type Tool = z.infer<typeof ToolSchema>;
+export type Transform = z.infer<typeof TransformSchema>;
+export type RemoteTool = z.infer<typeof RemoteToolSchema>;
+export type PlatformApiKey = z.infer<typeof PlatformApiKeySchema>;
+export type BillingLog = z.infer<typeof BillingLogSchema>;
+export type BillingLogRecord = BillingLog;
+export type BillingSummary = z.infer<typeof BillingSummarySchema>;
+export type BillingTransaction = z.infer<typeof BillingTransactionSchema>;
+export type BillingTransactionRecord = BillingTransaction;
+export type BalanceCheckResult = z.infer<typeof BalanceCheckSchema>;
+export type ModelPricing = z.infer<typeof ModelPricingSchema>;
+export type TemplateGallery = z.infer<typeof TemplateGallerySchema>;
+export type UpstreamProvider = z.infer<typeof UpstreamProviderSchema>;
+export type UpstreamProviderRecord = UpstreamProvider;

package/src/resources.ts

@@ -0,0 +1,163 @@
+import { z } from "zod";
+
+const nonEmptyString = z.string().min(1);
+const sourceExtension = z.enum([".js", ".ts"]);
+const remoteToolType = z.literal("mcp_streamable_http");
+const remoteToolOauthMode = z.literal("none");
+const stringList = z.array(nonEmptyString);
+const jsonRecord = z.record(z.string(), z.unknown());
+
+export const CreateModelRequestSchema = z.object({
+  providerNamespaceId: nonEmptyString,
+  code: nonEmptyString,
+  sourceCode: z.string().optional(),
+  sourceExtension: sourceExtension.optional(),
+});
+export const UpdateModelRequestSchema = CreateModelRequestSchema.partial()
+  .extend({
+    status: z.enum(["draft", "deployed", "disabled"]).optional(),
+  })
+  .refine((input) => Object.keys(input).length > 0)
+  .transform((input) => ({
+    ...(input.providerNamespaceId === undefined
+      ? {}
+      : { providerNamespaceId: input.providerNamespaceId }),
+    ...(input.code === undefined ? {} : { code: input.code }),
+    ...(input.sourceCode === undefined ? {} : { sourceCode: input.sourceCode }),
+    ...(input.sourceExtension === undefined
+      ? {}
+      : { sourceExtension: input.sourceExtension }),
+    ...(input.status === undefined ? {} : { status: input.status }),
+  }));
+export const UpsertModelSourceRequestSchema = z.object({
+  namespaceCode: nonEmptyString,
+  modelCode: nonEmptyString,
+  sourceCode: z.string().min(1),
+  sourceExtension,
+});
+
+export const CreateToolRequestSchema = z.object({
+  displayName: nonEmptyString,
+  sourceCode: z.string().optional(),
+  sourceExtension: sourceExtension.optional(),
+  attachedModelIds: stringList.optional(),
+});
+export const UpdateToolRequestSchema = CreateToolRequestSchema.partial()
+  .refine((input) => Object.keys(input).length > 0)
+  .transform((input) => ({
+    ...(input.displayName === undefined
+      ? {}
+      : { displayName: input.displayName }),
+    ...(input.sourceCode === undefined ? {} : { sourceCode: input.sourceCode }),
+    ...(input.sourceExtension === undefined
+      ? {}
+      : { sourceExtension: input.sourceExtension }),
+    ...(input.attachedModelIds === undefined
+      ? {}
+      : { attachedModelIds: input.attachedModelIds }),
+  }));
+
+export const CreateTransformRequestSchema = z.object({
+  code: nonEmptyString,
+  sourceCode: z.string().optional(),
+  sourceExtension: sourceExtension.optional(),
+});
+export const UpdateTransformRequestSchema =
+  CreateTransformRequestSchema.partial()
+    .refine((input) => Object.keys(input).length > 0)
+    .transform((input) => ({
+      ...(input.code === undefined ? {} : { code: input.code }),
+      ...(input.sourceCode === undefined
+        ? {}
+        : { sourceCode: input.sourceCode }),
+      ...(input.sourceExtension === undefined
+        ? {}
+        : { sourceExtension: input.sourceExtension }),
+    }));
+
+export const RemoteMcpToolSnapshotSchema = z.object({
+  name: nonEmptyString,
+  description: z.string(),
+  inputSchema: jsonRecord,
+});
+const remoteToolRequest = z.object({
+  code: nonEmptyString,
+  displayName: nonEmptyString,
+  type: remoteToolType,
+  endpointUrl: z.string().optional(),
+  staticHeaders: z.record(z.string(), z.string()).optional(),
+  oauthMode: remoteToolOauthMode.optional(),
+  attachedModelIds: stringList.optional(),
+});
+export const CreateRemoteToolRequestSchema = remoteToolRequest.transform(
+  (input) => ({
+    code: input.code,
+    displayName: input.displayName,
+    type: input.type,
+    ...(input.endpointUrl === undefined
+      ? {}
+      : { endpointUrl: input.endpointUrl }),
+    ...(input.staticHeaders === undefined
+      ? {}
+      : { staticHeaders: input.staticHeaders }),
+    ...(input.oauthMode === undefined ? {} : { oauthMode: input.oauthMode }),
+    ...(input.attachedModelIds === undefined
+      ? {}
+      : { attachedModelIds: input.attachedModelIds }),
+  }),
+);
+export const UpdateRemoteToolRequestSchema = remoteToolRequest
+  .partial()
+  .extend({
+    discoveredTools: z.array(RemoteMcpToolSnapshotSchema).optional(),
+    lastRefreshedAt: z.string().nullable().optional(),
+    lastRefreshError: z.string().nullable().optional(),
+  })
+  .refine((input) => Object.keys(input).length > 0)
+  .transform((input) => ({
+    ...(input.code === undefined ? {} : { code: input.code }),
+    ...(input.displayName === undefined
+      ? {}
+      : { displayName: input.displayName }),
+    ...(input.type === undefined ? {} : { type: input.type }),
+    ...(input.endpointUrl === undefined
+      ? {}
+      : { endpointUrl: input.endpointUrl }),
+    ...(input.staticHeaders === undefined
+      ? {}
+      : { staticHeaders: input.staticHeaders }),
+    ...(input.oauthMode === undefined ? {} : { oauthMode: input.oauthMode }),
+    ...(input.attachedModelIds === undefined
+      ? {}
+      : { attachedModelIds: input.attachedModelIds }),
+    ...(input.discoveredTools === undefined
+      ? {}
+      : { discoveredTools: input.discoveredTools }),
+    ...(input.lastRefreshedAt === undefined
+      ? {}
+      : { lastRefreshedAt: input.lastRefreshedAt }),
+    ...(input.lastRefreshError === undefined
+      ? {}
+      : { lastRefreshError: input.lastRefreshError }),
+  }));
+
+export type CreateModelRequest = z.infer<typeof CreateModelRequestSchema>;
+export type UpdateModelRequest = z.infer<typeof UpdateModelRequestSchema>;
+export type UpsertModelSourceRequest = z.infer<
+  typeof UpsertModelSourceRequestSchema
+>;
+export type CreateToolRequest = z.infer<typeof CreateToolRequestSchema>;
+export type UpdateToolRequest = z.infer<typeof UpdateToolRequestSchema>;
+export type CreateTransformRequest = z.infer<
+  typeof CreateTransformRequestSchema
+>;
+export type UpdateTransformRequest = z.infer<
+  typeof UpdateTransformRequestSchema
+>;
+export type CreateRemoteToolRequest = z.infer<
+  typeof CreateRemoteToolRequestSchema
+>;
+export type UpdateRemoteToolRequest = z.infer<
+  typeof UpdateRemoteToolRequestSchema
+>;
+export type RemoteMcpToolSnapshot = z.infer<typeof RemoteMcpToolSnapshotSchema>;

package/src/runtime-jwt.test.ts

@@ -0,0 +1,106 @@
+import { exportJWK, generateKeyPair } from "jose";
+import { describe, expect, it } from "vitest";
+import {
+  createRuntimeJwtIssuer,
+  RuntimeJwtIssueInputSchema,
+  verifyRuntimeJwt,
+} from "./runtime-jwt.ts";
+
+describe("runtime JWT contracts", () => {
+  it("verifies valid claims and enforces workspace, audience, and revocation", async () => {
+    const issuer = await testIssuer("key-1");
+    const token = await issuer.issue({
+      workspaceId: "workspace-1",
+      keyId: "api-key-1",
+      expiresAt: futureDate(),
+      allowedModels: ["default/chat"],
+      allowedNamespaces: null,
+    });
+    const config = {
+      jwksJson: issuer.publicJwksJson(),
+      workspaceId: "workspace-1",
+    };
+
+    await expect(verifyRuntimeJwt(token, config)).resolves.toEqual({
+      workspaceId: "workspace-1",
+      keyId: "api-key-1",
+      allowedModels: ["default/chat"],
+      allowedNamespaces: null,
+    });
+    await expect(
+      verifyRuntimeJwt(token, { ...config, workspaceId: "other" }),
+    ).resolves.toBeNull();
+    await expect(
+      verifyRuntimeJwt(token, { ...config, audience: "other" }),
+    ).resolves.toBeNull();
+    await expect(
+      verifyRuntimeJwt(token, { ...config, revokedKeyIds: ["api-key-1"] }),
+    ).resolves.toBeNull();
+  });
+
+  it("rejects expired and malformed tokens", async () => {
+    const issuer = await testIssuer("key-1");
+    const expired = await issuer.issue({
+      workspaceId: "workspace-1",
+      keyId: "api-key-1",
+      expiresAt: new Date(Date.now() - 1_000).toISOString(),
+      allowedModels: null,
+      allowedNamespaces: null,
+    });
+    const config = { jwksJson: issuer.publicJwksJson() };
+
+    await expect(verifyRuntimeJwt(expired, config)).resolves.toBeNull();
+    await expect(verifyRuntimeJwt(`${expired}x`, config)).resolves.toBeNull();
+  });
+
+  it("accepts active keys during key rotation", async () => {
+    const previous = await testIssuer("old-key");
+    const current = await testIssuer("new-key");
+    const jwksJson = JSON.stringify({
+      keys: [
+        ...jwks(previous.publicJwksJson()),
+        ...jwks(current.publicJwksJson()),
+      ],
+    });
+    const input = {
+      workspaceId: "workspace-1",
+      keyId: "api-key-1",
+      expiresAt: futureDate(),
+      allowedModels: null,
+      allowedNamespaces: ["default"],
+    };
+
+    await expect(
+      verifyRuntimeJwt(await previous.issue(input), { jwksJson }),
+    ).resolves.not.toBeNull();
+    await expect(
+      verifyRuntimeJwt(await current.issue(input), { jwksJson }),
+    ).resolves.not.toBeNull();
+  });
+
+  it("rejects malformed issue input at the schema boundary", () => {
+    expect(
+      RuntimeJwtIssueInputSchema.safeParse({
+        workspaceId: "workspace-1",
+        keyId: "api-key-1",
+        expiresAt: "not-a-date",
+        allowedModels: ["default/chat", 1],
+        allowedNamespaces: null,
+      }).success,
+    ).toBe(false);
+  });
+});
+
+async function testIssuer(keyId: string) {
+  const pair = await generateKeyPair("ES256", { extractable: true });
+  const privateJwk = await exportJWK(pair.privateKey);
+  return createRuntimeJwtIssuer(JSON.stringify({ ...privateJwk, kid: keyId }));
+}
+
+function futureDate(): string {
+  return new Date(Date.now() + 60_000).toISOString();
+}
+
+function jwks(value: string): JsonWebKey[] {
+  return (JSON.parse(value) as { keys: JsonWebKey[] }).keys;
+}

package/src/runtime-jwt.ts

@@ -0,0 +1,201 @@
+import { SignJWT, createLocalJWKSet, importJWK, jwtVerify } from "jose";
+import { z } from "zod";
+
+export const RUNTIME_JWT_ISSUER = "neutrome-platform";
+export const RUNTIME_JWT_AUDIENCE = "workspace-runtime";
+
+const nonEmptyString = z.string().min(1);
+const nullableStringArray = z
+  .array(z.string())
+  .nullish()
+  .transform((value) => value ?? null);
+const runtimeJwk = z
+  .object({
+    kty: z.literal("EC"),
+    crv: z.literal("P-256"),
+    x: nonEmptyString,
+    y: nonEmptyString,
+  })
+  .passthrough();
+const parseJson = <T extends z.ZodType>(schema: T) =>
+  z
+    .string()
+    .transform((value, context) => {
+      try {
+        return JSON.parse(value);
+      } catch {
+        context.addIssue({ code: "custom", message: "Expected JSON" });
+        return z.NEVER;
+      }
+    })
+    .pipe(schema);
+const privateRuntimeJwkJson = parseJson(
+  runtimeJwk.extend({ d: nonEmptyString }),
+);
+const runtimeJwksJson = parseJson(z.object({ keys: z.array(runtimeJwk) }));
+const revocationsJson = parseJson(z.array(nonEmptyString));
+const envString = nonEmptyString.optional();
+
+export const RuntimeJwtClaimsSchema = z.object({
+  workspaceId: nonEmptyString,
+  keyId: nonEmptyString,
+  allowedModels: nullableStringArray,
+  allowedNamespaces: nullableStringArray,
+});
+const runtimeJwtPayload = z
+  .object({
+    sub: nonEmptyString,
+    jti: nonEmptyString,
+    models: nullableStringArray,
+    namespaces: nullableStringArray,
+  })
+  .transform(({ sub, jti, models, namespaces }) => ({
+    workspaceId: sub,
+    keyId: jti,
+    allowedModels: models,
+    allowedNamespaces: namespaces,
+  }));
+
+export type RuntimeJwtClaims = z.infer<typeof RuntimeJwtClaimsSchema>;
+export const RuntimeJwtIssueInputSchema = RuntimeJwtClaimsSchema.extend({
+  expiresAt: z
+    .string()
+    .refine((value) => Number.isFinite(new Date(value).getTime()), {
+      message: "Runtime JWT expiration must be an ISO timestamp",
+    }),
+});
+export type RuntimeJwtIssueInput = z.infer<typeof RuntimeJwtIssueInputSchema>;
+
+export type RuntimeJwtIssuer = {
+  publicJwksJson(): string;
+  issue(input: RuntimeJwtIssueInput): Promise<string>;
+};
+
+export type RuntimeJwtVerificationConfig = {
+  jwksJson: string;
+  issuer?: string;
+  audience?: string;
+  revokedKeyIds?: readonly string[];
+  workspaceId?: string;
+};
+
+export type RuntimeJwtAuthenticator = {
+  authenticate(
+    request: Request,
+    env: Record<string, unknown>,
+  ): Promise<RuntimeJwtClaims | null>;
+};
+
+export type RuntimeJwtAuthConfig = Omit<
+  RuntimeJwtVerificationConfig,
+  "jwksJson" | "revokedKeyIds"
+> & {
+  jwksJson?: string;
+  revokedKeyIdsJson?: string;
+};
+
+export function createRuntimeJwtIssuer(
+  privateJwkJson: string,
+): RuntimeJwtIssuer {
+  const privateJwk = privateRuntimeJwkJson.parse(privateJwkJson);
+  const keyId = nonEmptyString.safeParse(privateJwk.kid).data ?? "runtime-key";
+
+  return {
+    publicJwksJson() {
+      const { d: _d, key_ops: _keyOps, ...publicJwk } = privateJwk;
+      return JSON.stringify({
+        keys: [{ ...publicJwk, kid: keyId, alg: "ES256", use: "sig" }],
+      });
+    },
+    async issue(input) {
+      const parsedInput = RuntimeJwtIssueInputSchema.parse(input);
+      const expiresAt = Math.floor(
+        new Date(parsedInput.expiresAt).getTime() / 1000,
+      );
+      const key = await importJWK(privateJwk, "ES256");
+      return new SignJWT({
+        ...(parsedInput.allowedModels
+          ? { models: parsedInput.allowedModels }
+          : {}),
+        ...(parsedInput.allowedNamespaces
+          ? { namespaces: parsedInput.allowedNamespaces }
+          : {}),
+      })
+        .setProtectedHeader({ alg: "ES256", kid: keyId, typ: "JWT" })
+        .setIssuer(RUNTIME_JWT_ISSUER)
+        .setAudience(RUNTIME_JWT_AUDIENCE)
+        .setSubject(parsedInput.workspaceId)
+        .setJti(parsedInput.keyId)
+        .setIssuedAt()
+        .setExpirationTime(expiresAt)
+        .sign(key);
+    },
+  };
+}
+
+export async function verifyRuntimeJwt(
+  token: string,
+  config: RuntimeJwtVerificationConfig,
+): Promise<RuntimeJwtClaims | null> {
+  try {
+    const jwks = createLocalJWKSet(runtimeJwksJson.parse(config.jwksJson));
+    const { payload } = await jwtVerify(token, jwks, {
+      issuer: config.issuer ?? RUNTIME_JWT_ISSUER,
+      audience: config.audience ?? RUNTIME_JWT_AUDIENCE,
+    });
+    const claims = runtimeJwtPayload.safeParse(payload);
+    if (
+      !claims.success ||
+      (config.workspaceId && claims.data.workspaceId !== config.workspaceId)
+    )
+      return null;
+    if (config.revokedKeyIds?.includes(claims.data.keyId)) return null;
+    return claims.data;
+  } catch {
+    return null;
+  }
+}
+
+export function createRuntimeJwtAuthenticator(
+  config: RuntimeJwtAuthConfig = {},
+): RuntimeJwtAuthenticator {
+  return {
+    async authenticate(request, env) {
+      const token = readRuntimeToken(request);
+      if (!token) return null;
+      const issuer =
+        config.issuer ?? envString.safeParse(env.LIL_RUNTIME_AUTH_ISSUER).data;
+      const audience =
+        config.audience ??
+        envString.safeParse(env.LIL_RUNTIME_AUTH_AUDIENCE).data;
+      return verifyRuntimeJwt(token, {
+        jwksJson:
+          config.jwksJson ??
+          envString.safeParse(env.LIL_RUNTIME_AUTH_JWKS_JSON).data ??
+          "",
+        revokedKeyIds:
+          revocationsJson.safeParse(
+            config.revokedKeyIdsJson ??
+              envString.safeParse(env.LIL_RUNTIME_REVOKED_KEY_IDS_JSON).data ??
+              "[]",
+          ).data ?? [],
+        ...(issuer ? { issuer } : {}),
+        ...(audience ? { audience } : {}),
+        ...(config.workspaceId ? { workspaceId: config.workspaceId } : {}),
+      });
+    },
+  };
+}
+
+function readRuntimeToken(request: Request): string | null {
+  const bearer = request.headers
+    .get("authorization")
+    ?.match(/^Bearer\s+(.+)$/i)?.[1];
+  if (bearer) return bearer;
+  return (
+    request.headers.get("x-api-key") ??
+    request.headers.get("x-goog-api-key") ??
+    new URL(request.url).searchParams.get("key") ??
+    new URL(request.url).searchParams.get("api_key")
+  );
+}

package/src/workspace.ts

@@ -0,0 +1,17 @@
+import { z } from "zod";
+
+const nonEmptyString = z.string().min(1);
+export const CreateWorkspaceInputSchema = z.object({
+  code: nonEmptyString,
+  displayName: nonEmptyString,
+});
+export const UpdateWorkspaceInputSchema = CreateWorkspaceInputSchema.partial()
+  .refine((input) => Object.keys(input).length > 0)
+  .transform((input): { code?: string; displayName?: string } => ({
+    ...(input.code === undefined ? {} : { code: input.code }),
+    ...(input.displayName === undefined
+      ? {}
+      : { displayName: input.displayName }),
+  }));
+export type CreateWorkspaceInput = z.infer<typeof CreateWorkspaceInputSchema>;
+export type UpdateWorkspaceInput = z.infer<typeof UpdateWorkspaceInputSchema>;

package/tsconfig.json

@@ -0,0 +1,17 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "lib": ["ES2022", "DOM"],
+    "strict": true,
+    "allowImportingTsExtensions": true,
+    "rewriteRelativeImportExtensions": true,
+    "noUncheckedIndexedAccess": true,
+    "exactOptionalPropertyTypes": true,
+    "skipLibCheck": true,
+    "noEmit": true,
+    "types": ["vitest/globals"]
+  },
+  "include": ["src/**/*.ts"]
+}