@opengeni/contracts 0.50.0 → 1.0.0

package/src/managed-auth-session-sets.ts

@@ -0,0 +1,253 @@
+import { z } from "zod";
+
+export const MANAGED_AUTH_SESSION_SET_MAX_SLOTS = 8 as const;
+export const MANAGED_AUTH_TRANSACTION_TTL_SECONDS = 600 as const;
+export const MANAGED_AUTH_RETURN_INTENT_MAX_BYTES = 2_048 as const;
+export const MANAGED_AUTH_SESSION_SET_API_CONTRACT_HEADER = "x-opengeni-api-contract" as const;
+export const MANAGED_AUTH_SESSION_SET_API_CONTRACT_REVISION =
+  "2026-08-personal-only-organization-setup-v1" as const;
+
+export const ManagedAuthSessionSetMode = z.enum(["legacy", "dual", "broker"]);
+export type ManagedAuthSessionSetMode = z.infer<typeof ManagedAuthSessionSetMode>;
+
+export const ManagedAuthLoginSlotState = z.enum(["active", "reauth_required"]);
+export type ManagedAuthLoginSlotState = z.infer<typeof ManagedAuthLoginSlotState>;
+
+export const ManagedAuthVerifiedClaim = z.object({
+  kind: z.literal("email"),
+  value: z.string().email().max(320),
+});
+export type ManagedAuthVerifiedClaim = z.infer<typeof ManagedAuthVerifiedClaim>;
+
+/** Secret-free, browser-safe summary. Provider session ids and tokens never enter this shape. */
+export const ManagedAuthLoginSlot = z.object({
+  id: z.string().uuid(),
+  displayName: z.string().min(1).max(256),
+  verifiedClaim: ManagedAuthVerifiedClaim,
+  state: ManagedAuthLoginSlotState,
+});
+export type ManagedAuthLoginSlot = z.infer<typeof ManagedAuthLoginSlot>;
+
+export const ManagedAuthSessionSetState = z.enum(["ready", "actor_change_required"]);
+export type ManagedAuthSessionSetState = z.infer<typeof ManagedAuthSessionSetState>;
+
+export const ManagedAuthSessionSetProjection = z.object({
+  mode: ManagedAuthSessionSetMode,
+  generation: z.string().regex(/^[1-9][0-9]*$/),
+  actorEpoch: z.string().regex(/^[1-9][0-9]*$/),
+  csrfToken: z.string().min(32).max(512),
+  selectedSlotId: z.string().uuid().nullable(),
+  state: ManagedAuthSessionSetState,
+  slots: z.array(ManagedAuthLoginSlot).max(MANAGED_AUTH_SESSION_SET_MAX_SLOTS),
+});
+export type ManagedAuthSessionSetProjection = z.infer<typeof ManagedAuthSessionSetProjection>;
+
+export const ManagedAuthOperationIdentity = z.object({
+  operationId: z.string().uuid(),
+  expectedGeneration: z.string().regex(/^[1-9][0-9]*$/),
+});
+export type ManagedAuthOperationIdentity = z.infer<typeof ManagedAuthOperationIdentity>;
+
+export const BootstrapManagedAuthSessionSetRequest = ManagedAuthOperationIdentity;
+export type BootstrapManagedAuthSessionSetRequest = z.infer<
+  typeof BootstrapManagedAuthSessionSetRequest
+>;
+
+export const ManagedAuthReturnIntent = z
+  .string()
+  .min(1)
+  .superRefine((value, context) => {
+    if (new TextEncoder().encode(value).byteLength > MANAGED_AUTH_RETURN_INTENT_MAX_BYTES) {
+      context.addIssue({ code: "custom", message: "return intent exceeds its UTF-8 byte limit" });
+    }
+    if (
+      !value.startsWith("/") ||
+      value.startsWith("//") ||
+      value.includes("?") ||
+      value.includes("#") ||
+      /[\u0000-\u001f\u007f\\]/.test(value)
+    ) {
+      context.addIssue({
+        code: "custom",
+        message: "return intent must be a safe same-origin path",
+      });
+      return;
+    }
+    try {
+      const parsed = new URL(value, "https://opengeni.invalid");
+      const uuid = "[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}";
+      const supportedPath = new RegExp(
+        `^/(?:sessions/${uuid}|workspaces/${uuid}(?:/sessions(?:/${uuid})?)?)$`,
+        "i",
+      );
+      if (
+        parsed.origin !== "https://opengeni.invalid" ||
+        parsed.username ||
+        parsed.password ||
+        parsed.search ||
+        parsed.hash ||
+        !supportedPath.test(value) ||
+        parsed.pathname !== value
+      ) {
+        context.addIssue({
+          code: "custom",
+          message: "return intent contains unsafe authority data",
+        });
+      }
+    } catch {
+      context.addIssue({
+        code: "custom",
+        message: "return intent is not a valid same-origin path",
+      });
+    }
+  });
+
+export const BeginManagedAuthLoginTransactionRequest = ManagedAuthOperationIdentity.extend({
+  kind: z.enum(["add", "reauth"]),
+  slotId: z.string().uuid().optional(),
+  returnIntent: ManagedAuthReturnIntent.optional(),
+}).superRefine((value, context) => {
+  if ((value.kind === "reauth") !== Boolean(value.slotId)) {
+    context.addIssue({
+      code: "custom",
+      path: ["slotId"],
+      message: "reauth requires exactly one slot id and add forbids one",
+    });
+  }
+});
+export type BeginManagedAuthLoginTransactionRequest = z.infer<
+  typeof BeginManagedAuthLoginTransactionRequest
+>;
+
+export const ManagedAuthLoginTransaction = z.object({
+  id: z.string().uuid(),
+  kind: z.enum(["add", "reauth"]),
+  expiresAt: z.string().datetime(),
+  returnIntentId: z.string().uuid().nullable(),
+});
+export type ManagedAuthLoginTransaction = z.infer<typeof ManagedAuthLoginTransaction>;
+
+export const ManagedAuthSocialProvider = z.enum(["google", "github"]);
+export type ManagedAuthSocialProvider = z.infer<typeof ManagedAuthSocialProvider>;
+
+/**
+ * Mirrors `SignupAttribution` from `./signup-attribution` (a contract test pins
+ * them together). Declared here, not imported, so the browser session-set
+ * client does not pull the attribution module into a new shared web chunk.
+ */
+const SocialStartAttributionValue = z
+  .string()
+  .trim()
+  .min(1)
+  .max(100)
+  .regex(/^[A-Za-z0-9._~+-]+$/);
+const SocialStartAttribution = z
+  .object({
+    utmSource: SocialStartAttributionValue.optional(),
+    utmMedium: SocialStartAttributionValue.optional(),
+    utmCampaign: SocialStartAttributionValue.optional(),
+    utmContent: SocialStartAttributionValue.optional(),
+    ref: SocialStartAttributionValue.optional(),
+  })
+  .strict();
+
+export const StartManagedAuthSocialTransactionRequest = ManagedAuthOperationIdentity.extend({
+  transactionId: z.string().uuid(),
+  provider: ManagedAuthSocialProvider,
+  /**
+   * Optional untrusted first-touch campaign tokens, used only by the
+   * content-free sign-up acquisition counter when this start creates a new
+   * account. Invalid attribution is dropped rather than failing the sign-in.
+   */
+  attribution: SocialStartAttribution.optional().catch(undefined),
+});
+export type StartManagedAuthSocialTransactionRequest = z.infer<
+  typeof StartManagedAuthSocialTransactionRequest
+>;
+
+export const StartManagedAuthSocialTransactionResponse = z.object({
+  url: z.string().url().max(4_096),
+});
+export type StartManagedAuthSocialTransactionResponse = z.infer<
+  typeof StartManagedAuthSocialTransactionResponse
+>;
+
+export const CompleteManagedAuthEmailPasswordTransactionRequest =
+  ManagedAuthOperationIdentity.extend({
+    transactionId: z.string().uuid(),
+    email: z.string().email().max(320),
+    password: z.string().min(1).max(1_024),
+  });
+export type CompleteManagedAuthEmailPasswordTransactionRequest = z.infer<
+  typeof CompleteManagedAuthEmailPasswordTransactionRequest
+>;
+
+export const CompleteManagedAuthLoginTransactionResponse = z.object({
+  projection: ManagedAuthSessionSetProjection,
+  returnIntent: ManagedAuthReturnIntent.nullable(),
+});
+export type CompleteManagedAuthLoginTransactionResponse = z.infer<
+  typeof CompleteManagedAuthLoginTransactionResponse
+>;
+
+export const CancelManagedAuthLoginTransactionRequest = ManagedAuthOperationIdentity.extend({
+  transactionId: z.string().uuid(),
+});
+export type CancelManagedAuthLoginTransactionRequest = z.infer<
+  typeof CancelManagedAuthLoginTransactionRequest
+>;
+
+export const SelectManagedAuthLoginSlotRequest = ManagedAuthOperationIdentity.extend({
+  slotId: z.string().uuid(),
+});
+export type SelectManagedAuthLoginSlotRequest = z.infer<typeof SelectManagedAuthLoginSlotRequest>;
+
+export const LogoutManagedAuthLoginSlotRequest = ManagedAuthOperationIdentity.extend({
+  slotId: z.string().uuid(),
+  replacementSlotId: z.string().uuid().nullable(),
+});
+export type LogoutManagedAuthLoginSlotRequest = z.infer<typeof LogoutManagedAuthLoginSlotRequest>;
+
+export const LogoutManagedAuthSessionSetRequest = ManagedAuthOperationIdentity;
+export type LogoutManagedAuthSessionSetRequest = z.infer<typeof LogoutManagedAuthSessionSetRequest>;
+
+export const ManagedAuthLogoutAllReceipt = z.object({
+  generation: z.string().regex(/^[1-9][0-9]*$/),
+  actorEpoch: z.string().regex(/^[1-9][0-9]*$/),
+  state: z.literal("logged_out"),
+});
+export type ManagedAuthLogoutAllReceipt = z.infer<typeof ManagedAuthLogoutAllReceipt>;
+
+export const ResolveManagedAuthDeepLinkRequest = z.object({
+  path: ManagedAuthReturnIntent,
+});
+export type ResolveManagedAuthDeepLinkRequest = z.infer<typeof ResolveManagedAuthDeepLinkRequest>;
+
+export const ManagedAuthDeepLinkResolution = z.discriminatedUnion("kind", [
+  z.object({ kind: z.literal("current") }),
+  z.object({ kind: z.literal("switch_required"), slot: ManagedAuthLoginSlot }),
+  z.object({ kind: z.literal("unavailable") }),
+]);
+export type ManagedAuthDeepLinkResolution = z.infer<typeof ManagedAuthDeepLinkResolution>;
+
+export const ManagedAuthSessionSetErrorCode = z.enum([
+  "actor_change_required",
+  "actor_mutation_in_flight",
+  "api_contract_changed",
+  "browser_session_set_required",
+  "browser_session_set_unavailable",
+  "generation_conflict",
+  "invalid_browser_session_set_request",
+  "invalid_transaction",
+  "managed_authentication_required",
+  "managed_authentication_unavailable",
+  "operation_outcome_unknown",
+  "operation_reused",
+  "origin_rejected",
+  "login_transaction_rate_limited",
+  "provider_route_blocked",
+  "slot_limit_reached",
+  "slot_already_exists",
+  "slot_unavailable",
+]);
+export type ManagedAuthSessionSetErrorCode = z.infer<typeof ManagedAuthSessionSetErrorCode>;

package/src/managed-sign-in-methods.ts

@@ -0,0 +1,37 @@
+import { z } from "zod";
+
+export const ManagedSignInProvider = z.enum(["google", "github"]);
+export const ManagedSignInMethods = z.object({
+  identityId: z.string().uuid(),
+  email: z.string().email(),
+  emailVerified: z.boolean(),
+  identityRevision: z.number().int().positive(),
+  freshAuthenticationRequired: z.boolean(),
+  methods: z.array(
+    z.object({
+      provider: z.enum(["credential", "google", "github"]),
+      connected: z.boolean(),
+      available: z.boolean(),
+      canDisconnect: z.boolean(),
+      implicitRelinkingSuppressed: z.boolean(),
+    }),
+  ),
+});
+export type ManagedSignInMethods = z.infer<typeof ManagedSignInMethods>;
+export const ManagedSignInMutation = z.object({
+  expectedIdentityId: z.string().uuid(),
+  operationId: z.string().uuid(),
+  expectedIdentityRevision: z.number().int().positive(),
+});
+export const ManagedSignInProviderMutation = ManagedSignInMutation.extend({
+  provider: ManagedSignInProvider,
+}).strict();
+export const ManagedSignInPasswordMutation = ManagedSignInMutation.extend({
+  newPassword: z.string().min(8).max(128),
+  currentPassword: z.string().min(1).max(1024).optional(),
+}).strict();
+export const ManagedSignInMutationResponse = z.object({
+  reauthenticationRequired: z.literal(true),
+  notification: z.enum(["sent", "failed", "outcome_unknown"]),
+});
+export const ManagedSignInConnectResponse = z.object({ url: z.string().url() });

package/src/mcp-catalog-limits.ts

@@ -0,0 +1,2 @@
+/** Shared discovery and explicit permission-selection count allowance. */
+export const MCP_MAX_CATALOG_TOOL_ENTRIES = 4_096;

package/src/mcp-endpoint.ts

@@ -0,0 +1,30 @@
+/** Exact endpoint identity: normalize URL syntax, preserve paths and query parameters. */
+export function mcpEndpointIdentity(value: string | null | undefined): string | null {
+  if (!value) return null;
+  try {
+    const url = new URL(value);
+    if (!["https:", "http:"].includes(url.protocol) || url.username || url.password) return null;
+    url.hash = "";
+    return url.href;
+  } catch {
+    return null;
+  }
+}
+
+export function pluginMcpUnavailableReason(server: {
+  endpoint: string | null;
+  transport?: string;
+  requiresConfiguration?: boolean;
+}): string | null {
+  if (server.transport === "stdio" || !server.endpoint) return "Requires a local runtime";
+  if (
+    server.transport &&
+    !["http", "streamable-http", "streamable_http"].includes(server.transport)
+  )
+    return "Unsupported transport: " + server.transport;
+  if (server.requiresConfiguration || server.endpoint.includes("{"))
+    return "Requires custom connection configuration";
+  const endpoint = mcpEndpointIdentity(server.endpoint);
+  if (!endpoint?.startsWith("https://")) return "Requires a valid HTTPS endpoint";
+  return null;
+}

package/src/mcp-oauth.ts

@@ -0,0 +1,66 @@
+import { z } from "zod";
+
+export const MCP_OAUTH_SCOPE = "mcp:access" as const;
+export const MCP_OAUTH_ACCESS_TOKEN_TTL_SECONDS = 15 * 60;
+export const MCP_OAUTH_REFRESH_TOKEN_TTL_SECONDS = 30 * 24 * 60 * 60;
+export const MCP_OAUTH_AUTHORIZATION_CODE_TTL_SECONDS = 5 * 60;
+export const MCP_OAUTH_CONSENT_TTL_SECONDS = 10 * 60;
+
+const RedirectUri = z.string().url().max(2_048);
+
+export const McpOAuthClientRegistrationRequest = z.object({
+  redirect_uris: z.array(RedirectUri).min(1).max(16),
+  client_name: z.string().trim().min(1).max(200).optional(),
+  application_type: z.enum(["native", "web"]).optional(),
+  token_endpoint_auth_method: z.literal("none").default("none"),
+  scope: z.literal(MCP_OAUTH_SCOPE).optional(),
+  grant_types: z
+    .array(z.enum(["authorization_code", "refresh_token"]))
+    .min(1)
+    .max(2)
+    .refine((grantTypes) => grantTypes.includes("authorization_code"), {
+      message: "authorization_code grant is required",
+    })
+    .default(["authorization_code", "refresh_token"]),
+  response_types: z.array(z.literal("code")).min(1).max(1).default(["code"]),
+});
+export type McpOAuthClientRegistrationRequest = z.infer<typeof McpOAuthClientRegistrationRequest>;
+
+export const McpOAuthClientRegistrationResponse = McpOAuthClientRegistrationRequest.extend({
+  client_id: z.string().min(1).max(256),
+  client_id_issued_at: z.number().int().nonnegative(),
+});
+export type McpOAuthClientRegistrationResponse = z.infer<typeof McpOAuthClientRegistrationResponse>;
+
+export const McpOAuthTokenResponse = z.object({
+  access_token: z.string().min(1),
+  token_type: z.literal("Bearer"),
+  expires_in: z.number().int().positive(),
+  refresh_token: z.string().min(1).optional(),
+  scope: z.literal(MCP_OAUTH_SCOPE),
+});
+export type McpOAuthTokenResponse = z.infer<typeof McpOAuthTokenResponse>;
+
+export const McpOAuthProtectedResourceMetadata = z.object({
+  resource: z.string().url(),
+  authorization_servers: z.array(z.string().url()).min(1).max(1),
+  scopes_supported: z.array(z.literal(MCP_OAUTH_SCOPE)).length(1),
+  bearer_methods_supported: z.array(z.literal("header")).length(1),
+});
+export type McpOAuthProtectedResourceMetadata = z.infer<typeof McpOAuthProtectedResourceMetadata>;
+
+export const McpOAuthAuthorizationServerMetadata = z.object({
+  issuer: z.string().url(),
+  authorization_endpoint: z.string().url(),
+  token_endpoint: z.string().url(),
+  registration_endpoint: z.string().url(),
+  response_types_supported: z.array(z.literal("code")).length(1),
+  grant_types_supported: z.array(z.enum(["authorization_code", "refresh_token"])).length(2),
+  code_challenge_methods_supported: z.array(z.literal("S256")).length(1),
+  token_endpoint_auth_methods_supported: z.array(z.literal("none")).length(1),
+  scopes_supported: z.array(z.literal(MCP_OAUTH_SCOPE)).length(1),
+  authorization_response_iss_parameter_supported: z.literal(true),
+});
+export type McpOAuthAuthorizationServerMetadata = z.infer<
+  typeof McpOAuthAuthorizationServerMetadata
+>;