@sealant/api-contracts-next 0.0.0-next.0 → 0.39.0-next.682

package/dist/core-api/ssh-keys.d.ts

@@ -0,0 +1,120 @@
+import { Schema } from "effect";
+import { HttpApiEndpoint, HttpApiGroup } from "effect/unstable/httpapi";
+export declare const sshKeyGatewayHeadersSchema: Schema.Struct<{
+    readonly "x-sealant-gateway-token": Schema.optional<Schema.String>;
+}>;
+export type SshKeyGatewayHeaders = typeof sshKeyGatewayHeadersSchema.Type;
+export declare const createSshKeyRequestSchema: Schema.Struct<{
+    readonly ownerUserId: Schema.String;
+    readonly name: Schema.optional<Schema.String>;
+    readonly publicKey: Schema.String;
+}>;
+export type CreateSshKeyRequest = typeof createSshKeyRequestSchema.Type;
+export declare const sshKeySummarySchema: Schema.Struct<{
+    readonly sshKeyId: Schema.String;
+    readonly ownerUserId: Schema.String;
+    readonly name: Schema.String;
+    readonly algorithm: Schema.String;
+    readonly fingerprint: Schema.String;
+    readonly createdAt: Schema.String;
+}>;
+export type SshKeySummary = typeof sshKeySummarySchema.Type;
+export declare const listSshKeysQuerySchema: Schema.Struct<{
+    readonly ownerUserId: Schema.String;
+}>;
+export declare const listSshKeysResponseSchema: Schema.Struct<{
+    readonly items: Schema.$Array<Schema.Struct<{
+        readonly sshKeyId: Schema.String;
+        readonly ownerUserId: Schema.String;
+        readonly name: Schema.String;
+        readonly algorithm: Schema.String;
+        readonly fingerprint: Schema.String;
+        readonly createdAt: Schema.String;
+    }>>;
+}>;
+export type ListSshKeysResponse = typeof listSshKeysResponseSchema.Type;
+export declare const resolveSshPrincipalRequestSchema: Schema.Struct<{
+    readonly algo: Schema.String;
+    readonly publicKeyBase64: Schema.String;
+}>;
+export type ResolveSshPrincipalRequest = typeof resolveSshPrincipalRequestSchema.Type;
+export declare const resolveSshPrincipalResponseSchema: Schema.Struct<{
+    readonly principalId: Schema.String;
+    readonly sshKeyId: Schema.String;
+    readonly fingerprint: Schema.String;
+}>;
+export type ResolveSshPrincipalResponse = typeof resolveSshPrincipalResponseSchema.Type;
+declare const SshKeyBadRequestError_base: Schema.Class<SshKeyBadRequestError, Schema.TaggedStruct<"SshKeyBadRequestError", {
+    readonly message: Schema.String;
+}>, import("effect/Cause").YieldableError>;
+export declare class SshKeyBadRequestError extends SshKeyBadRequestError_base {
+}
+declare const SshKeyUnauthorizedError_base: Schema.Class<SshKeyUnauthorizedError, Schema.TaggedStruct<"SshKeyUnauthorizedError", {
+    readonly message: Schema.String;
+}>, import("effect/Cause").YieldableError>;
+export declare class SshKeyUnauthorizedError extends SshKeyUnauthorizedError_base {
+}
+declare const SshKeyNotFoundError_base: Schema.Class<SshKeyNotFoundError, Schema.TaggedStruct<"SshKeyNotFoundError", {
+    readonly message: Schema.String;
+}>, import("effect/Cause").YieldableError>;
+export declare class SshKeyNotFoundError extends SshKeyNotFoundError_base {
+}
+declare const SshKeyConflictError_base: Schema.Class<SshKeyConflictError, Schema.TaggedStruct<"SshKeyConflictError", {
+    readonly message: Schema.String;
+}>, import("effect/Cause").YieldableError>;
+export declare class SshKeyConflictError extends SshKeyConflictError_base {
+}
+declare const SshKeyServiceUnavailableError_base: Schema.Class<SshKeyServiceUnavailableError, Schema.TaggedStruct<"SshKeyServiceUnavailableError", {
+    readonly message: Schema.String;
+}>, import("effect/Cause").YieldableError>;
+export declare class SshKeyServiceUnavailableError extends SshKeyServiceUnavailableError_base {
+}
+declare const SshKeyInternalServerError_base: Schema.Class<SshKeyInternalServerError, Schema.TaggedStruct<"SshKeyInternalServerError", {
+    readonly message: Schema.String;
+}>, import("effect/Cause").YieldableError>;
+export declare class SshKeyInternalServerError extends SshKeyInternalServerError_base {
+}
+export declare const SshKeysGroup: HttpApiGroup.HttpApiGroup<"sshKeys", HttpApiEndpoint.HttpApiEndpoint<"archiveSshKey", "DELETE", "/:sshKeyId", HttpApiEndpoint.StringTree<Schema.Struct<{
+    readonly sshKeyId: Schema.String;
+}>>, HttpApiEndpoint.StringTree<Schema.Struct<{
+    readonly ownerUserId: Schema.String;
+}>>, HttpApiEndpoint.Json<never>, HttpApiEndpoint.StringTree<never>, HttpApiEndpoint.Json<Schema.Struct<{
+    readonly sshKeyId: Schema.String;
+    readonly ownerUserId: Schema.String;
+    readonly name: Schema.String;
+    readonly algorithm: Schema.String;
+    readonly fingerprint: Schema.String;
+    readonly createdAt: Schema.String;
+}>>, HttpApiEndpoint.Json<typeof SshKeyNotFoundError | typeof SshKeyInternalServerError>, never, never> | HttpApiEndpoint.HttpApiEndpoint<"createSshKey", "POST", "/", HttpApiEndpoint.StringTree<never>, HttpApiEndpoint.StringTree<never>, HttpApiEndpoint.Json<Schema.Struct<{
+    readonly ownerUserId: Schema.String;
+    readonly name: Schema.optional<Schema.String>;
+    readonly publicKey: Schema.String;
+}>>, HttpApiEndpoint.StringTree<never>, HttpApiEndpoint.Json<Schema.Struct<{
+    readonly sshKeyId: Schema.String;
+    readonly ownerUserId: Schema.String;
+    readonly name: Schema.String;
+    readonly algorithm: Schema.String;
+    readonly fingerprint: Schema.String;
+    readonly createdAt: Schema.String;
+}>>, HttpApiEndpoint.Json<typeof SshKeyBadRequestError | typeof SshKeyNotFoundError | typeof SshKeyConflictError | typeof SshKeyInternalServerError>, never, never> | HttpApiEndpoint.HttpApiEndpoint<"listSshKeys", "GET", "/", HttpApiEndpoint.StringTree<never>, HttpApiEndpoint.StringTree<Schema.Struct<{
+    readonly ownerUserId: Schema.String;
+}>>, HttpApiEndpoint.StringTree<never>, HttpApiEndpoint.StringTree<never>, HttpApiEndpoint.Json<Schema.Struct<{
+    readonly items: Schema.$Array<Schema.Struct<{
+        readonly sshKeyId: Schema.String;
+        readonly ownerUserId: Schema.String;
+        readonly name: Schema.String;
+        readonly algorithm: Schema.String;
+        readonly fingerprint: Schema.String;
+        readonly createdAt: Schema.String;
+    }>>;
+}>>, HttpApiEndpoint.Json<typeof SshKeyInternalServerError>, never, never> | HttpApiEndpoint.HttpApiEndpoint<"resolveSshPrincipal", "POST", "/resolve-principal", HttpApiEndpoint.StringTree<never>, HttpApiEndpoint.StringTree<never>, HttpApiEndpoint.Json<Schema.Struct<{
+    readonly algo: Schema.String;
+    readonly publicKeyBase64: Schema.String;
+}>>, HttpApiEndpoint.StringTree<Schema.Struct<{
+    readonly "x-sealant-gateway-token": Schema.optional<Schema.String>;
+}>>, HttpApiEndpoint.Json<Schema.Struct<{
+    readonly principalId: Schema.String;
+    readonly sshKeyId: Schema.String;
+    readonly fingerprint: Schema.String;
+}>>, HttpApiEndpoint.Json<typeof SshKeyUnauthorizedError | typeof SshKeyNotFoundError | typeof SshKeyServiceUnavailableError | typeof SshKeyInternalServerError>, never, never>, false>;
+export {};

package/dist/core-api/ssh-keys.js

@@ -0,0 +1,108 @@
+import { Schema } from "effect";
+import { HttpApiEndpoint, HttpApiGroup, HttpApiSchema, OpenApi } from "effect/unstable/httpapi";
+const NonEmptyString = Schema.String.check(Schema.isNonEmpty(), Schema.isTrimmed());
+/*
+User SSH public keys. Two audiences:
+- the web app (via its tRPC proxy) registers/lists/archives keys for the logged-in user;
+- the SSH gateway resolves an offered key to its owning principal at auth time via
+  `resolveSshPrincipal`, gated by the shared gateway token (same trust model as
+  `getWorkspaceSshTarget` in workspaces.ts).
+*/
+export const sshKeyGatewayHeadersSchema = Schema.Struct({
+    // Authenticates the gateway as a trusted caller of the internal resolve endpoint.
+    "x-sealant-gateway-token": Schema.optional(NonEmptyString),
+});
+export const createSshKeyRequestSchema = Schema.Struct({
+    // Same trust model as createWorkspace: the internal API trusts the caller-supplied owner; the web
+    // server injects the session user id.
+    ownerUserId: NonEmptyString,
+    name: Schema.optional(NonEmptyString),
+    // Raw `<algorithm> <base64> [comment]` line; the API normalizes and fingerprints it.
+    publicKey: NonEmptyString,
+});
+export const sshKeySummarySchema = Schema.Struct({
+    sshKeyId: NonEmptyString,
+    ownerUserId: NonEmptyString,
+    name: NonEmptyString,
+    algorithm: NonEmptyString,
+    fingerprint: NonEmptyString,
+    createdAt: Schema.String,
+});
+export const listSshKeysQuerySchema = Schema.Struct({
+    ownerUserId: NonEmptyString,
+});
+export const listSshKeysResponseSchema = Schema.Struct({
+    items: Schema.Array(sshKeySummarySchema),
+});
+export const resolveSshPrincipalRequestSchema = Schema.Struct({
+    // ctx.key.algo / base64(ctx.key.data) from the gateway's ssh2 auth context. The API recomputes
+    // the fingerprint server-side; callers never supply one.
+    algo: NonEmptyString,
+    publicKeyBase64: NonEmptyString,
+});
+export const resolveSshPrincipalResponseSchema = Schema.Struct({
+    principalId: NonEmptyString,
+    sshKeyId: NonEmptyString,
+    fingerprint: NonEmptyString,
+});
+export class SshKeyBadRequestError extends Schema.TaggedErrorClass()("SshKeyBadRequestError", {
+    message: Schema.String,
+}, { httpApiStatus: 400 }) {
+}
+export class SshKeyUnauthorizedError extends Schema.TaggedErrorClass()("SshKeyUnauthorizedError", {
+    message: Schema.String,
+}, { httpApiStatus: 401 }) {
+}
+export class SshKeyNotFoundError extends Schema.TaggedErrorClass()("SshKeyNotFoundError", {
+    message: Schema.String,
+}, { httpApiStatus: 404 }) {
+}
+export class SshKeyConflictError extends Schema.TaggedErrorClass()("SshKeyConflictError", {
+    message: Schema.String,
+}, { httpApiStatus: 409 }) {
+}
+export class SshKeyServiceUnavailableError extends Schema.TaggedErrorClass()("SshKeyServiceUnavailableError", {
+    message: Schema.String,
+}, { httpApiStatus: 503 }) {
+}
+export class SshKeyInternalServerError extends Schema.TaggedErrorClass()("SshKeyInternalServerError", {
+    message: Schema.String,
+}, { httpApiStatus: 500 }) {
+}
+const sshKeyIdParams = Schema.Struct({ sshKeyId: NonEmptyString });
+export const SshKeysGroup = HttpApiGroup.make("sshKeys")
+    .add(HttpApiEndpoint.post("createSshKey", "/", {
+    payload: createSshKeyRequestSchema,
+    success: sshKeySummarySchema.pipe(HttpApiSchema.status(201)),
+    error: [
+        SshKeyBadRequestError,
+        SshKeyNotFoundError,
+        SshKeyConflictError,
+        SshKeyInternalServerError,
+    ],
+}))
+    .add(HttpApiEndpoint.get("listSshKeys", "/", {
+    query: listSshKeysQuerySchema,
+    success: listSshKeysResponseSchema,
+    error: [SshKeyInternalServerError],
+}))
+    .add(HttpApiEndpoint.delete("archiveSshKey", "/:sshKeyId", {
+    params: sshKeyIdParams,
+    query: listSshKeysQuerySchema,
+    success: sshKeySummarySchema,
+    error: [SshKeyNotFoundError, SshKeyInternalServerError],
+}))
+    .add(
+// POST (not GET) so key material stays out of URLs and access logs.
+HttpApiEndpoint.post("resolveSshPrincipal", "/resolve-principal", {
+    headers: sshKeyGatewayHeadersSchema,
+    payload: resolveSshPrincipalRequestSchema,
+    success: resolveSshPrincipalResponseSchema,
+    error: [
+        SshKeyUnauthorizedError,
+        SshKeyNotFoundError,
+        SshKeyServiceUnavailableError,
+        SshKeyInternalServerError,
+    ],
+}))
+    .annotate(OpenApi.Description, "User SSH public keys and gateway principal resolution.");

package/dist/core-api/system.d.ts

@@ -0,0 +1,51 @@
+import { Schema } from "effect";
+import { HttpApiEndpoint, HttpApiGroup } from "effect/unstable/httpapi";
+export declare const systemIndexResponseSchema: Schema.Struct<{
+    readonly name: Schema.String;
+    readonly version: Schema.String;
+    readonly docsPath: Schema.String;
+    readonly openApiPath: Schema.String;
+}>;
+export type SystemIndexResponse = typeof systemIndexResponseSchema.Type;
+export declare const systemHealthResponseSchema: Schema.Struct<{
+    readonly status: Schema.Literal<"ok">;
+}>;
+export type SystemHealthResponse = typeof systemHealthResponseSchema.Type;
+export declare const setupStateSshGatewaySchema: Schema.Struct<{
+    readonly host: Schema.String;
+    readonly port: Schema.Number;
+    readonly usernamePrefix: Schema.String;
+}>;
+export type SetupStateSshGateway = typeof setupStateSshGatewaySchema.Type;
+export declare const setupStateResponseSchema: Schema.Struct<{
+    readonly needsSetup: Schema.Boolean;
+    readonly sshGateway: Schema.NullOr<Schema.Struct<{
+        readonly host: Schema.String;
+        readonly port: Schema.Number;
+        readonly usernamePrefix: Schema.String;
+    }>>;
+}>;
+export type SetupStateResponse = typeof setupStateResponseSchema.Type;
+declare const SystemInternalServerError_base: Schema.Class<SystemInternalServerError, Schema.TaggedStruct<"SystemInternalServerError", {
+    readonly message: Schema.String;
+}>, import("effect/Cause").YieldableError>;
+export declare class SystemInternalServerError extends SystemInternalServerError_base {
+}
+export declare const SystemGroup: HttpApiGroup.HttpApiGroup<"system", HttpApiEndpoint.HttpApiEndpoint<"getIndex", "GET", "/", HttpApiEndpoint.StringTree<never>, HttpApiEndpoint.StringTree<never>, HttpApiEndpoint.StringTree<never>, HttpApiEndpoint.StringTree<never>, HttpApiEndpoint.Json<Schema.Struct<{
+    readonly name: Schema.String;
+    readonly version: Schema.String;
+    readonly docsPath: Schema.String;
+    readonly openApiPath: Schema.String;
+}>>, HttpApiEndpoint.Json<never>, never, never> | HttpApiEndpoint.HttpApiEndpoint<"getSetupState", "GET", "/v1/system/setup-state", HttpApiEndpoint.StringTree<never>, HttpApiEndpoint.StringTree<never>, HttpApiEndpoint.StringTree<never>, HttpApiEndpoint.StringTree<never>, HttpApiEndpoint.Json<Schema.Struct<{
+    readonly needsSetup: Schema.Boolean;
+    readonly sshGateway: Schema.NullOr<Schema.Struct<{
+        readonly host: Schema.String;
+        readonly port: Schema.Number;
+        readonly usernamePrefix: Schema.String;
+    }>>;
+}>>, HttpApiEndpoint.Json<typeof SystemInternalServerError>, never, never> | HttpApiEndpoint.HttpApiEndpoint<"health", "GET", "/healthz", HttpApiEndpoint.StringTree<never>, HttpApiEndpoint.StringTree<never>, HttpApiEndpoint.StringTree<never>, HttpApiEndpoint.StringTree<never>, HttpApiEndpoint.Json<Schema.Struct<{
+    readonly status: Schema.Literal<"ok">;
+}>>, HttpApiEndpoint.Json<never>, never, never> | HttpApiEndpoint.HttpApiEndpoint<"ready", "GET", "/readyz", HttpApiEndpoint.StringTree<never>, HttpApiEndpoint.StringTree<never>, HttpApiEndpoint.StringTree<never>, HttpApiEndpoint.StringTree<never>, HttpApiEndpoint.Json<Schema.Struct<{
+    readonly status: Schema.Literal<"ok">;
+}>>, HttpApiEndpoint.Json<never>, never, never>, false>;
+export {};

package/dist/core-api/system.js

@@ -0,0 +1,41 @@
+import { Schema } from "effect";
+import { HttpApiEndpoint, HttpApiGroup, OpenApi } from "effect/unstable/httpapi";
+const NonEmptyString = Schema.String.check(Schema.isNonEmpty(), Schema.isTrimmed());
+export const systemIndexResponseSchema = Schema.Struct({
+    name: NonEmptyString,
+    version: NonEmptyString,
+    docsPath: NonEmptyString,
+    openApiPath: NonEmptyString,
+});
+export const systemHealthResponseSchema = Schema.Struct({
+    status: Schema.Literal("ok"),
+});
+export const setupStateSshGatewaySchema = Schema.Struct({
+    host: NonEmptyString,
+    // Defaults (22 / "ws") are applied server-side so clients never hardcode them.
+    port: Schema.Number,
+    usernamePrefix: NonEmptyString,
+});
+export const setupStateResponseSchema = Schema.Struct({
+    // True while nobody can sign in (zero better-auth accounts); drives the first-run wizard. The
+    // seeded SDK owner (usr_local) has no credentials and does not count.
+    needsSetup: Schema.Boolean,
+    // Null when WORKSPACE_SSH_GATEWAY_HOST is not configured on the API.
+    sshGateway: Schema.NullOr(setupStateSshGatewaySchema),
+});
+export class SystemInternalServerError extends Schema.TaggedErrorClass()("SystemInternalServerError", {
+    message: Schema.String,
+}, { httpApiStatus: 500 }) {
+}
+export const SystemGroup = HttpApiGroup.make("system")
+    .add(HttpApiEndpoint.get("getIndex", "/", { success: systemIndexResponseSchema }))
+    .add(HttpApiEndpoint.get("health", "/healthz", { success: systemHealthResponseSchema }))
+    .add(HttpApiEndpoint.get("ready", "/readyz", { success: systemHealthResponseSchema }))
+    .add(
+// Public by design: pre-auth gating in the web app needs it. Exposes only needsSetup and the
+// gateway connect coordinates (host/port/prefix), which every workspace endpoint echoes anyway.
+HttpApiEndpoint.get("getSetupState", "/v1/system/setup-state", {
+    success: setupStateResponseSchema,
+    error: [SystemInternalServerError],
+}))
+    .annotate(OpenApi.Description, "System metadata, health probes, and first-run setup state.");

package/dist/core-api/users.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Users wire contracts — identity rows for products that own their own login.
+ *
+ * A SERVICE PRINCIPAL (Mend) provisions one Sealant user per person and then acts on their behalf
+ * through the `ownerUserId` every owned endpoint carries. `ensureUser` is idempotent on email so
+ * the caller can run it on every sign-in without bookkeeping; the id is the owner id to use from
+ * then on. Sign-in credentials are never part of this surface — better-auth (web) owns those.
+ */
+import { Schema } from "effect";
+import { HttpApiEndpoint, HttpApiGroup } from "effect/unstable/httpapi";
+export declare const userSchema: Schema.Struct<{
+    readonly userId: Schema.String;
+    readonly email: Schema.String;
+    readonly name: Schema.String;
+    readonly createdAt: Schema.String;
+}>;
+export type UserWire = typeof userSchema.Type;
+export declare const ensureUserRequestSchema: Schema.Struct<{
+    /** Matched case-insensitively; the stored form is lower-cased. */
+    readonly email: Schema.String;
+    readonly name: Schema.String;
+    /** Caller-chosen id for a NEW user (`usr_…`); ignored when the email already exists. */
+    readonly userId: Schema.optional<Schema.String>;
+}>;
+export type EnsureUserRequest = typeof ensureUserRequestSchema.Type;
+export declare const ensureUserResponseSchema: Schema.Struct<{
+    readonly userId: Schema.String;
+    readonly email: Schema.String;
+    readonly name: Schema.String;
+    readonly createdAt: Schema.String;
+    /** True when this call created the user. */
+    readonly created: Schema.Boolean;
+}>;
+export type EnsureUserResponse = typeof ensureUserResponseSchema.Type;
+declare const UserBadRequestError_base: Schema.Class<UserBadRequestError, Schema.TaggedStruct<"UserBadRequestError", {
+    readonly message: Schema.String;
+}>, import("effect/Cause").YieldableError>;
+export declare class UserBadRequestError extends UserBadRequestError_base {
+}
+declare const UserNotFoundError_base: Schema.Class<UserNotFoundError, Schema.TaggedStruct<"UserNotFoundError", {
+    readonly message: Schema.String;
+}>, import("effect/Cause").YieldableError>;
+export declare class UserNotFoundError extends UserNotFoundError_base {
+}
+declare const UserInternalServerError_base: Schema.Class<UserInternalServerError, Schema.TaggedStruct<"UserInternalServerError", {
+    readonly message: Schema.String;
+}>, import("effect/Cause").YieldableError>;
+export declare class UserInternalServerError extends UserInternalServerError_base {
+}
+export declare const UsersGroup: HttpApiGroup.HttpApiGroup<"users", HttpApiEndpoint.HttpApiEndpoint<"ensureUser", "POST", "/", HttpApiEndpoint.StringTree<never>, HttpApiEndpoint.StringTree<never>, HttpApiEndpoint.Json<Schema.Struct<{
+    /** Matched case-insensitively; the stored form is lower-cased. */
+    readonly email: Schema.String;
+    readonly name: Schema.String;
+    /** Caller-chosen id for a NEW user (`usr_…`); ignored when the email already exists. */
+    readonly userId: Schema.optional<Schema.String>;
+}>>, HttpApiEndpoint.StringTree<never>, HttpApiEndpoint.Json<Schema.Struct<{
+    readonly userId: Schema.String;
+    readonly email: Schema.String;
+    readonly name: Schema.String;
+    readonly createdAt: Schema.String;
+    /** True when this call created the user. */
+    readonly created: Schema.Boolean;
+}>>, HttpApiEndpoint.Json<typeof UserBadRequestError | typeof UserInternalServerError>, never, never> | HttpApiEndpoint.HttpApiEndpoint<"getUser", "GET", "/:userId", HttpApiEndpoint.StringTree<Schema.Struct<{
+    readonly userId: Schema.String;
+}>>, HttpApiEndpoint.StringTree<never>, HttpApiEndpoint.StringTree<never>, HttpApiEndpoint.StringTree<never>, HttpApiEndpoint.Json<Schema.Struct<{
+    readonly userId: Schema.String;
+    readonly email: Schema.String;
+    readonly name: Schema.String;
+    readonly createdAt: Schema.String;
+}>>, HttpApiEndpoint.Json<typeof UserNotFoundError | typeof UserInternalServerError>, never, never>, false>;
+export {};

package/dist/core-api/users.js

@@ -0,0 +1,48 @@
+/**
+ * Users wire contracts — identity rows for products that own their own login.
+ *
+ * A SERVICE PRINCIPAL (Mend) provisions one Sealant user per person and then acts on their behalf
+ * through the `ownerUserId` every owned endpoint carries. `ensureUser` is idempotent on email so
+ * the caller can run it on every sign-in without bookkeeping; the id is the owner id to use from
+ * then on. Sign-in credentials are never part of this surface — better-auth (web) owns those.
+ */
+import { Schema } from "effect";
+import { HttpApiEndpoint, HttpApiGroup, OpenApi } from "effect/unstable/httpapi";
+const NonEmptyString = Schema.String.check(Schema.isNonEmpty(), Schema.isTrimmed());
+export const userSchema = Schema.Struct({
+    userId: NonEmptyString,
+    email: NonEmptyString,
+    name: NonEmptyString,
+    createdAt: Schema.String,
+});
+export const ensureUserRequestSchema = Schema.Struct({
+    /** Matched case-insensitively; the stored form is lower-cased. */
+    email: NonEmptyString,
+    name: NonEmptyString,
+    /** Caller-chosen id for a NEW user (`usr_…`); ignored when the email already exists. */
+    userId: Schema.optional(NonEmptyString),
+});
+export const ensureUserResponseSchema = Schema.Struct({
+    ...userSchema.fields,
+    /** True when this call created the user. */
+    created: Schema.Boolean,
+});
+export class UserBadRequestError extends Schema.TaggedErrorClass()("UserBadRequestError", { message: Schema.String }, { httpApiStatus: 400 }) {
+}
+export class UserNotFoundError extends Schema.TaggedErrorClass()("UserNotFoundError", { message: Schema.String }, { httpApiStatus: 404 }) {
+}
+export class UserInternalServerError extends Schema.TaggedErrorClass()("UserInternalServerError", { message: Schema.String }, { httpApiStatus: 500 }) {
+}
+const userIdParams = Schema.Struct({ userId: NonEmptyString });
+export const UsersGroup = HttpApiGroup.make("users")
+    .add(HttpApiEndpoint.post("ensureUser", "/", {
+    payload: ensureUserRequestSchema,
+    success: ensureUserResponseSchema,
+    error: [UserBadRequestError, UserInternalServerError],
+}))
+    .add(HttpApiEndpoint.get("getUser", "/:userId", {
+    params: userIdParams,
+    success: userSchema,
+    error: [UserNotFoundError, UserInternalServerError],
+}))
+    .annotate(OpenApi.Description, "Identity rows for products that own their own login and act on behalf of their users.");