@robelest/convex-auth 0.0.4-preview.25 → 0.0.4-preview.28

package/dist/server/sso/domain.d.ts

@@ -0,0 +1,614 @@
+import { ComponentCtx, ComponentReadCtx } from "../componentContext.js";
+import { ConvexAuthMaterializedConfig, GroupConnectionDeprovisionMode, GroupConnectionPolicy, GroupConnectionPolicyPatch, OIDCClaimMapping } from "../types.js";
+import { AuditEventRecord, ConnectionDomainRecord, GroupConnectionDomainLookupRecord, GroupConnectionListResult, GroupConnectionRecord, ScimConfigRecord, ScimIdentityRecord, WebhookDeliveryRecord, WebhookEndpointRecord } from "../contract.js";
+import { GenericActionCtx, GenericDataModel } from "convex/server";
+
+//#region src/server/sso/domain.d.ts
+type DomainDeps = {
+  config: ConvexAuthMaterializedConfig & {
+    extraProviders?: unknown[];
+  };
+  connectionNotFoundError: string;
+  GROUP_CONNECTION_OIDC_CLIENT_SECRET_KIND: "oidc_client_secret";
+  requireEnv: (name: string) => string;
+  generateRandomString: (length: number, alphabet: string) => string;
+  INVITE_TOKEN_ALPHABET: string;
+  sha256: (input: string) => Promise<string>;
+  encryptSecret: (value: string) => Promise<string>;
+  sharedOidcRedirectURI?: string;
+  getGroupConnectionSecret: (ctx: ComponentReadCtx, connectionId: string, kind: "oidc_client_secret") => Promise<Record<string, unknown> | null>;
+  loadConnectionOrThrow: (ctx: ComponentReadCtx, connectionId: string) => Promise<{
+    _id: string;
+    groupId: string;
+    protocol: "oidc" | "saml";
+    status: "draft" | "active" | "disabled";
+    config?: unknown;
+  }>;
+  validateGroupConnectionPolicy: (policy: GroupConnectionPolicy) => Array<{
+    name: string;
+    ok: boolean;
+    message?: string;
+  }>;
+  recordGroupAuditEvent: (ctx: ComponentCtx, data: {
+    connectionId?: string;
+    groupId: string;
+    eventType: string;
+    actorType: "user" | "system" | "scim" | "api_key" | "webhook";
+    actorId?: string;
+    subjectType: string;
+    subjectId?: string;
+    ok: boolean;
+    requestId?: string;
+    ip?: string;
+    metadata?: Record<string, unknown>;
+  }) => Promise<string>;
+  emitGroupWebhookDeliveries: (ctx: ComponentCtx, data: {
+    connectionId: string;
+    eventType: string;
+    payload: Record<string, unknown>;
+    auditEventId?: string;
+  }) => Promise<void>;
+  loadGroupPolicyOrThrow: (ctx: ComponentReadCtx, groupId: string) => Promise<GroupConnectionPolicy>;
+};
+/**
+ * Build the connection and SSO management domain.
+ */
+declare function createGroupConnectionDomain<TDeps extends DomainDeps>(deps: TDeps): {
+  connection: {
+    create: (ctx: ComponentCtx, data: {
+      groupId: string;
+      protocol: "oidc" | "saml";
+      slug?: string;
+      name?: string;
+      status?: "draft" | "active" | "disabled";
+      config?: Record<string, unknown>;
+      extend?: Record<string, unknown>;
+    }) => Promise<{
+      connectionId: string;
+      groupId: string;
+    }>;
+    get: (ctx: ComponentReadCtx, connectionId: string) => Promise<GroupConnectionRecord | null>;
+    getByDomain: (ctx: ComponentReadCtx, domain: string) => Promise<GroupConnectionDomainLookupRecord | null>;
+    list: (ctx: ComponentReadCtx, opts?: {
+      where?: {
+        groupId?: string;
+        slug?: string;
+        status?: "draft" | "active" | "disabled";
+      };
+      limit?: number;
+      cursor?: string | null;
+      orderBy?: "_creationTime" | "name" | "slug" | "status";
+      order?: "asc" | "desc";
+    }) => Promise<GroupConnectionListResult>;
+    update: (ctx: ComponentCtx, connectionId: string, data: Record<string, unknown>) => Promise<{
+      connectionId: string;
+    }>;
+    delete: (ctx: ComponentCtx, connectionId: string) => Promise<{
+      connectionId: string;
+    }>;
+    /**
+     * Aggregate readiness status across all configured protocols for an
+     * group connection.
+     *
+     * Returns a structured result indicating whether the connection is
+     * ready, with per-protocol checks so callers can surface actionable
+     * diagnostics without running full network validation.
+     */
+    status: (ctx: ComponentReadCtx, connectionId: string) => Promise<{
+      connectionId: string;
+      status: "draft" | "active" | "disabled";
+      ready: boolean;
+      domainCount: number;
+      protocols: {
+        oidc: {
+          configured: boolean;
+          ready: boolean;
+          clientId: string | null;
+          issuer: string | null;
+        };
+        saml: {
+          configured: boolean;
+          ready: boolean;
+          entityId: string | null;
+        };
+        scim: {
+          configured: boolean;
+          ready: boolean;
+          basePath: string | null;
+          deprovisionMode: GroupConnectionDeprovisionMode;
+        };
+      };
+    }>;
+  };
+  domain: {
+    add: (ctx: ComponentCtx, data: {
+      connectionId: string;
+      groupId: string;
+      domain: string;
+      isPrimary?: boolean;
+    }) => Promise<string>;
+    list: (ctx: ComponentReadCtx, connectionId: string) => Promise<ConnectionDomainRecord[]>;
+    validate: (ctx: ComponentReadCtx, connectionId: string) => Promise<{
+      connectionId: string;
+      ready: boolean;
+      summary: {
+        domainCount: number;
+        primaryCount: number;
+        verifiedCount: number;
+      };
+      domains: {
+        domainId: string;
+        domain: string;
+        isPrimary: boolean;
+        verified: boolean;
+        verifiedAt: number | null;
+      }[];
+      warnings: string[];
+    }>;
+    status: (ctx: ComponentReadCtx, connectionId: string) => Promise<{
+      connectionId: string;
+      ready: boolean;
+      primaryDomain: {
+        domainId: string;
+        domain: string;
+        isPrimary: boolean;
+        verified: boolean;
+        verifiedAt: number | null;
+      } | null;
+      trustedDomains: {
+        domainId: string;
+        domain: string;
+        isPrimary: boolean;
+        verified: boolean;
+        verifiedAt: number | null;
+      }[];
+      pendingChallenges: {
+        domain: string;
+        recordName: string;
+        expiresAt: number;
+      }[];
+      trust: {
+        domainDiscoveryReady: boolean;
+        primaryDomainVerified: boolean;
+        automaticLinkingEligible: boolean;
+      };
+      warnings: string[];
+      nextSteps: string[];
+    }>;
+    remove: (ctx: ComponentCtx, domainId: string) => Promise<void>;
+    verification: {
+      request: (ctx: ComponentCtx, args: {
+        connectionId: string;
+        domain: string;
+      }) => Promise<{
+        connectionId: string;
+        domain: string;
+        requestedAt: number;
+        expiresAt: number;
+        challenge: {
+          recordType: "TXT";
+          recordName: string;
+          recordValue: string;
+        };
+      }>;
+      confirm: (ctx: ComponentCtx, args: {
+        connectionId: string;
+        domain: string;
+      }) => Promise<{
+        connectionId: string;
+        domain: string;
+        checks: {
+          name: string;
+          ok: boolean;
+          message?: string;
+        }[];
+        verifiedAt?: undefined;
+      } | {
+        connectionId: string;
+        domain: string;
+        verifiedAt: number;
+        checks: {
+          name: string;
+          ok: boolean;
+          message?: string;
+        }[];
+      }>;
+    };
+  };
+  saml: {
+    configure: <DataModel extends GenericDataModel>(ctx: GenericActionCtx<DataModel>, data: {
+      connectionId: string;
+      metadata: {
+        xml?: string;
+        url?: string;
+      };
+      domains?: string[];
+      request?: {
+        signAuthnRequests?: boolean;
+        nameIdFormat?: string;
+        forceAuthn?: boolean;
+        authnContextClassRefs?: string[];
+      };
+      security?: {
+        requireSignedAssertions?: boolean;
+        requireTimestamps?: boolean;
+        clockSkewSeconds?: number;
+        weakAlgorithmHandling?: "warn" | "reject";
+        maxMetadataSize?: number;
+        maxResponseSize?: number;
+      };
+      serviceProvider?: {
+        entityId?: string;
+        acsUrl?: string;
+        sloUrl?: string;
+        signingCert?: string | string[];
+        encryptCert?: string | string[];
+        privateKey?: string;
+        privateKeyPass?: string;
+        encPrivateKey?: string;
+        encPrivateKeyPass?: string;
+      };
+      profile?: {
+        mapping?: {
+          subject?: string;
+          email?: string;
+          name?: string;
+          firstName?: string;
+          lastName?: string;
+          image?: string;
+          groups?: string;
+          roles?: string;
+        };
+        extraFields?: Record<string, string>;
+      };
+    }) => Promise<{
+      connectionId: string;
+      groupId: string;
+    }>;
+    refresh: (ctx: ComponentCtx, data: {
+      connectionId: string;
+    }) => Promise<{
+      connectionId: string;
+      groupId: string;
+    }>;
+    get: (ctx: ComponentReadCtx, connectionId: string) => Promise<Record<string, unknown>>;
+    status: (ctx: ComponentReadCtx, connectionId: string) => Promise<{
+      connectionId: string;
+      configured: boolean;
+      ready: boolean;
+      config: Record<string, unknown>;
+      checks: {
+        name: string;
+        ok: boolean;
+        message: string | undefined;
+      }[];
+    }>;
+    metadata: <DataModel extends GenericDataModel>(ctx: GenericActionCtx<DataModel>, opts: {
+      connectionId: string;
+      entityId?: string;
+      acsUrl?: string;
+      sloUrl?: string;
+    }) => Promise<string>;
+    /**
+     * Validate the stored SAML config for an group connection.
+     *
+     * Re-parses IdP metadata, checks signing cert presence, and verifies
+     * SP metadata can be generated. Returns a structured result with
+     * per-check details rather than throwing on first failure.
+     */
+    validate: <DataModel extends GenericDataModel>(ctx: GenericActionCtx<DataModel>, connectionId: string) => Promise<{
+      ok: boolean;
+      connectionId: string;
+      checks: {
+        name: string;
+        ok: boolean;
+        message?: string;
+      }[];
+    }>;
+  };
+  policy: {
+    get: (ctx: ComponentReadCtx, groupId: string) => Promise<GroupConnectionPolicy>;
+    update: (ctx: ComponentCtx, groupId: string, patch: GroupConnectionPolicyPatch) => Promise<GroupConnectionPolicy>;
+    validate: (ctx: ComponentReadCtx, groupId: string) => Promise<{
+      ok: boolean;
+      groupId: string;
+      checks: {
+        name: string;
+        ok: boolean;
+        message: string;
+      }[];
+      policy?: undefined;
+    } | {
+      ok: boolean;
+      groupId: string;
+      policy: GroupConnectionPolicy;
+      checks: {
+        name: string;
+        ok: boolean;
+        message?: string;
+      }[];
+    }>;
+  };
+  oidc: {
+    /**
+     * Register or update connection OIDC connection settings.
+     *
+     * Persists protocol config under `connection.config.protocols.oidc` and
+     * records a `group.sso.oidc.registered` audit event.
+     */
+    configure: (ctx: ComponentCtx, data: {
+      connectionId: string;
+      discovery: {
+        issuer?: string;
+        discoveryUrl?: string;
+        jwksUri?: string;
+        audience?: string | string[];
+      };
+      client: {
+        id: string;
+        secret?: string;
+        authMethod?: "client_secret_post" | "client_secret_basic";
+      };
+      request?: {
+        scopes?: string[];
+        loginHint?: string;
+        authorizationParams?: Record<string, string>;
+      };
+      security?: {
+        clockToleranceSeconds?: number;
+        strictIssuer?: boolean;
+      };
+      profile?: {
+        mapping?: OIDCClaimMapping;
+        extraFields?: Record<string, string>;
+      };
+    }) => Promise<{
+      hasClientSecret: boolean;
+    }>;
+    /**
+     * Fetch the stored OIDC config for an connection.
+     */
+    get: (ctx: ComponentReadCtx, connectionId: string) => Promise<{
+      hasClientSecret: boolean;
+    }>;
+    status: (ctx: ComponentReadCtx, connectionId: string) => Promise<{
+      connectionId: string;
+      configured: boolean;
+      ready: boolean;
+      config: {
+        hasClientSecret: boolean;
+      };
+      checks: {
+        name: string;
+        ok: boolean;
+        message: string | undefined;
+      }[];
+    }>;
+    /**
+     * Resolve group SSO sign-in route from connection id, domain, or
+     * user email domain.
+     */
+    signIn: (ctx: ComponentReadCtx, data: {
+      connectionId?: string;
+      email?: string;
+      domain?: string;
+      redirectTo?: string;
+      loginHint?: string;
+    }) => Promise<{
+      connectionId: string;
+      protocol: "oidc" | "saml";
+      providerId: string;
+      signInPath: string;
+      callbackPath: string;
+      redirectTo: string | undefined;
+    }>;
+    /**
+     * Validate the stored OIDC config for an group connection.
+     *
+     * Fetches the OIDC discovery document from the configured issuer or
+     * discoveryUrl, verifies required fields are present, and checks that
+     * clientId is set. Returns a structured result with per-check details.
+     */
+    validate: (ctx: ComponentReadCtx, connectionId: string) => Promise<{
+      ok: boolean;
+      connectionId: string;
+      checks: {
+        name: string;
+        ok: boolean;
+        message?: string;
+      }[];
+    }>;
+  };
+  scim: {
+    configure: (ctx: ComponentCtx, data: {
+      connectionId: string;
+      status?: "draft" | "active" | "disabled";
+      security?: {
+        maxRequestSize?: number;
+      };
+      profile?: {
+        mapping?: {
+          subject?: string;
+          externalId?: string;
+          email?: string;
+          firstName?: string;
+          lastName?: string;
+          name?: string;
+          phone?: string;
+          active?: string;
+          groups?: string;
+          roles?: string;
+        };
+        extraFields?: Record<string, string>;
+      };
+    }) => Promise<{
+      connectionId: string;
+      configId: string;
+      basePath: string;
+      token: string;
+    }>;
+    get: (ctx: ComponentReadCtx, connectionId: string) => Promise<{
+      security: {
+        maxRequestSize?: number;
+      } | undefined;
+      profile: {
+        mapping?: {
+          subject?: string;
+          externalId?: string;
+          email?: string;
+          firstName?: string;
+          lastName?: string;
+          name?: string;
+          phone?: string;
+          active?: string;
+          groups?: string;
+          roles?: string;
+        };
+        extraFields?: Record<string, string>;
+      } | undefined;
+      _id: string;
+      _creationTime: number;
+      connectionId: string;
+      groupId: string;
+      status: string;
+      basePath: string;
+      tokenHash: string;
+      lastRotatedAt?: number;
+      extend?: unknown;
+    } | null>;
+    status: (ctx: ComponentReadCtx, connectionId: string) => Promise<{
+      connectionId: string;
+      configured: boolean;
+      ready: boolean;
+      config: ScimConfigRecord | null;
+      checks: {
+        name: string;
+        ok: boolean;
+        message?: string;
+      }[] | {
+        name: string;
+        ok: boolean;
+        message: string;
+      }[];
+      capabilities: {
+        users: boolean;
+        groups: boolean;
+        patch: boolean;
+        put: boolean;
+        filters: string[];
+        bulk: boolean;
+        etag: boolean;
+      } | undefined;
+    }>;
+    getConfigByToken: (ctx: ComponentReadCtx, token: string) => Promise<ScimConfigRecord | null>;
+    validate: (ctx: ComponentReadCtx, connectionId: string) => Promise<{
+      ok: boolean;
+      connectionId: string;
+      checks: {
+        name: string;
+        ok: boolean;
+        message: string;
+      }[];
+      basePath?: undefined;
+      deprovisionMode?: undefined;
+      capabilities?: undefined;
+    } | {
+      ok: boolean;
+      connectionId: string;
+      basePath: string;
+      deprovisionMode: GroupConnectionDeprovisionMode;
+      capabilities: {
+        users: boolean;
+        groups: boolean;
+        patch: boolean;
+        put: boolean;
+        filters: string[];
+        bulk: boolean;
+        etag: boolean;
+      };
+      checks: {
+        name: string;
+        ok: boolean;
+        message?: string;
+      }[];
+    }>;
+    identity: {
+      get: (ctx: ComponentReadCtx, data: {
+        connectionId: string;
+        resourceType: "user" | "group";
+        externalId: string;
+      }) => Promise<ScimIdentityRecord | null>;
+      upsert: (ctx: ComponentCtx, data: {
+        connectionId: string;
+        groupId: string;
+        resourceType: "user" | "group";
+        externalId: string;
+        userId?: string;
+        mappedGroupId?: string;
+        active?: boolean;
+        raw?: Record<string, unknown>;
+      }) => Promise<string>;
+    };
+  };
+  audit: {
+    record: (ctx: ComponentCtx, data: {
+      connectionId: string;
+      groupId: string;
+      eventType: string;
+      actorType: "user" | "system" | "scim" | "api_key" | "webhook";
+      actorId?: string;
+      subjectType: string;
+      subjectId?: string;
+      ok: boolean;
+      requestId?: string;
+      ip?: string;
+      metadata?: Record<string, unknown>;
+    }) => Promise<string>;
+    list: (ctx: ComponentReadCtx, data: {
+      connectionId?: string;
+      groupId?: string;
+      limit?: number;
+    }) => Promise<AuditEventRecord[]>;
+  };
+  webhook: {
+    endpoint: {
+      get: (ctx: ComponentReadCtx, endpointId: string) => Promise<WebhookEndpointRecord | null>;
+      create: (ctx: ComponentCtx, data: {
+        connectionId: string;
+        url: string;
+        secret: string;
+        subscriptions: string[];
+        createdByUserId?: string;
+      }) => Promise<{
+        endpointId: string;
+      }>;
+      list: (ctx: ComponentReadCtx, connectionId: string) => Promise<WebhookEndpointRecord[]>;
+      disable: (ctx: ComponentCtx, endpointId: string) => Promise<{
+        endpointId: string;
+      }>;
+    };
+    emit: (ctx: ComponentCtx, data: {
+      connectionId: string;
+      eventType: string;
+      payload: Record<string, unknown>;
+      auditEventId?: string;
+    }) => Promise<void>;
+    delivery: {
+      list: (ctx: ComponentReadCtx, data: {
+        connectionId: string;
+        limit?: number;
+      }) => Promise<WebhookDeliveryRecord[]>;
+      listReady: (ctx: ComponentReadCtx, limit?: number) => Promise<WebhookDeliveryRecord[]>;
+      markDelivered: (ctx: ComponentCtx, deliveryId: string, responseStatus?: number) => Promise<void>;
+      markFailed: (ctx: ComponentCtx, deliveryId: string, data: {
+        attemptCount: number;
+        responseStatus?: number;
+        error?: string;
+        retryAt?: number;
+      }) => Promise<void>;
+    };
+  };
+};
+//#endregion
+export { createGroupConnectionDomain };
+//# sourceMappingURL=domain.d.ts.map