better-supabase 0.8.0 → 0.9.0

package/dist/blocks/sso/index.d.ts

@@ -1,132 +1,144 @@
 /// <reference lib="esnext.temporal" />
-import { t as AsyncResult, w as ErrorMapper } from "../../result-BchM1XZn.js";
-import { a as dbTransport, o as rpcTransport, s as sqlTransport, t as BlockTransport } from "../../block-transport-inD4fFq-.js";
-import { r as BlockTemporalOptions } from "../../block-helpers-C0Xj8War.js";
-import { s as ApiKeys } from "../../api-keys-C8BlF3L2.js";
-//#region src/blocks/sso/sso.d.ts
-/** The DNS record that proves a domain belongs to the organization. */
-interface DomainRecord {
-  readonly type: "TXT";
-  readonly name: string;
-  readonly value: string;
-}
-interface OrganizationDomain {
-  readonly id: string;
-  readonly organizationId: string;
-  readonly domain: string;
-  readonly verifiedAt: Temporal.Instant | undefined;
-  /** New users with a confirmed email at the domain join with this role. */
-  readonly autoJoinRole: string | undefined;
-  /** Sessions of users at the domain need SAML (`sso_access_token_check`). */
-  readonly enforceSso: boolean;
-  readonly createdBy: string | undefined;
-  readonly createdAt: Temporal.Instant;
-  /** Publish this TXT record, then call `verifyDomain`. */
-  readonly record: DomainRecord;
+import { f as Result } from "../../result-Cj3yWhjH.js";
+import { X as OrganizationDomainEventData, Z as OrganizationEventData, at as SsoProviderEventData, nt as ScimEventData, wt as Events } from "../../events-CTreRrgP.js";
+import { a as dbTransport, o as rpcTransport, s as sqlTransport, t as BlockTransport } from "../../block-transport-DaGGXjIw.js";
+import { r as BlockTemporalOptions } from "../../block-helpers-C86hPEjI.js";
+import { s as BlockOf } from "../../define-block-CLZMEFeK.js";
+import { l as ApiKeys } from "../../api-keys-BYoGCM9p.js";
+import { _ as dohResolver, a as SamlProviderInput, c as SsoAdmin, d as SsoDomain, f as SsoOptions, g as createSsoAdmin, h as createSso, i as SamlMetadata, l as SsoAdminOptions, m as TxtResolver, n as DomainRecord, o as Sso, p as SsoProvider, r as OrganizationDomain, s as SsoActor, t as DohResolverOptions, u as SsoAuthAdmin } from "../../sso-BN0LnMqE.js";
+//#region src/blocks/sso/scim-filter.d.ts
+type CompareOp = "eq" | "ne" | "co" | "sw" | "ew" | "gt" | "ge" | "lt" | "le";
+type ScimFilter = {
+  readonly op: "and" | "or";
+  readonly left: ScimFilter;
+  readonly right: ScimFilter;
+} | {
+  readonly op: "not";
+  readonly filter: ScimFilter;
+} | {
+  readonly op: "pr";
+  readonly path: string;
+} | {
+  readonly op: CompareOp;
+  readonly path: string;
+  readonly value: string | number | boolean | null;
+} | {
+  readonly op: "value";
+  readonly path: string;
+  readonly filter: ScimFilter;
+};
+/** A filter the service provider can't parse or apply: 400 `invalidFilter`. */
+export declare class ScimFilterError extends Error {
+  override readonly name = "ScimFilterError";
 }
-interface SsoProvider {
-  /** The Supabase Auth SSO provider id, for `signInWithSSO({ providerId })`. */
+/** Parses a SCIM filter; throws `ScimFilterError`. */
+declare function parseFilter(input: string): ScimFilter;
+/** Whether `resource` matches; a multi-valued attribute matches when any value does. */
+declare function matches(resource: Record<string, unknown>, filter: ScimFilter): boolean;
+//#endregion
+//#region src/blocks/sso/scim-store.d.ts
+type ScimResourceType = "User" | "Group";
+type Doc = Readonly<Record<string, unknown>>;
+/**
+ * A resource as a store keeps it: the SCIM attributes without `meta` and
+ * without `$ref`s, which the handler adds for the URL it serves.
+ */
+interface ScimStoredResource {
   readonly id: string;
-  readonly organizationId: string;
-  readonly type: "saml";
-  readonly metadataUrl: string | undefined;
-  readonly domains: readonly string[];
-  readonly createdAt: Temporal.Instant;
+  readonly resource: Doc;
+  /** Raised on every write; the ETag is `W/"<version>"`. */
+  readonly version: number;
+  readonly created: Temporal.Instant;
+  readonly lastModified: Temporal.Instant;
 }
-/** The provider an email address signs in with. */
-interface SsoDomain {
-  readonly domain: string;
-  readonly organizationId: string;
-  readonly providerId: string;
-  readonly enforceSso: boolean;
+interface ScimListQuery {
+  /** The parsed `filter`; a store may apply it or leave it to the handler. */
+  readonly filter: ScimFilter | undefined;
+  /** 1-based, as in RFC 7644 §3.4.2.4. */
+  readonly startIndex: number;
+  readonly count: number;
 }
-interface SsoOptions extends BlockTemporalOptions {
-  /** The caller's transport (`rpcTransport(supabase)`). */
-  readonly transport: BlockTransport;
-  /** The module schema (`sql.modules.sso.schema`), default `better_supabase`. */
-  readonly schema?: string;
-  readonly mappers?: readonly ErrorMapper[];
+interface ScimListPage {
+  readonly resources: readonly ScimStoredResource[];
+  /**
+   * Set when the store applied `filter`, `startIndex` and `count` itself:
+   * the handler then pages nothing and reports this total. Leave it out to
+   * return every resource of the tenant for the handler to filter and page.
+   */
+  readonly totalResults?: number;
 }
-interface Sso {
-  /** Claims a domain (needs `sso.manage`); publish its `record`, then verify it. */
-  addDomain(organizationId: string, domain: string): AsyncResult<OrganizationDomain>;
-  domains(organizationId: string): AsyncResult<readonly OrganizationDomain[]>;
-  /** Sets auto-join and SSO enforcement; both need a verified domain. */
-  updateDomain(domainId: string, settings: {
-    readonly autoJoinRole?: string | null;
-    readonly enforceSso?: boolean;
-  }): AsyncResult<OrganizationDomain>;
-  removeDomain(domainId: string): AsyncResult<boolean>;
-  providers(organizationId: string): AsyncResult<readonly SsoProvider[]>;
-  /** The SSO provider for an email address, for the sign-in page. Works signed out. */
-  domainFor(email: string): AsyncResult<SsoDomain | undefined>;
+interface ScimSaveInput {
+  /** `undefined` creates the resource. */
+  readonly id: string | undefined;
+  /**
+   * The resource the client sent, or the result of a PATCH, without
+   * `meta`. Extension schemas and their attributes are left in.
+   */
+  readonly resource: Doc;
+  /**
+   * The core attributes the handler validated. Users: `userName`,
+   * `externalId`, `displayName`, `givenName`, `familyName`, `emails` and
+   * `active`. Groups: `displayName`, `externalId` and `members` (ids).
+   */
+  readonly data: Doc;
+  /** The version an `If-Match` (or the read before a PUT or PATCH) requires. */
+  readonly version: number | undefined;
 }
-/** Organization domains and SSO lookups as the caller. */
-export declare function createSso(options: SsoOptions): Sso;
-/** Looks up the TXT strings at a name; an empty list when it has none. */
-type TxtResolver = (name: string, signal?: AbortSignal) => Promise<readonly string[]>;
-interface DohResolverOptions {
-  /** A DNS-over-HTTPS JSON endpoint. Default Cloudflare's `https://cloudflare-dns.com/dns-query`. */
-  readonly endpoint?: string;
-  readonly fetch?: typeof fetch;
+/**
+ * Where the SCIM handler keeps users and groups. `sqlScimStore` is the
+ * default; another store can relay to a directory or a provider. Errors are
+ * `DbError`s: `not_found` answers 404, `stale` 412, `conflict` 409, and
+ * `invalid_input` or `validation` 400.
+ */
+interface ScimStore {
+  readonly apiVersion: 1;
+  list(type: ScimResourceType, tenant: string, query: ScimListQuery): Promise<Result<ScimListPage>>;
+  /** `undefined` when the tenant has no resource with this id. */
+  get(type: ScimResourceType, tenant: string, id: string): Promise<Result<ScimStoredResource | undefined>>;
+  save(type: ScimResourceType, tenant: string, input: ScimSaveInput): Promise<Result<ScimStoredResource>>;
+  /** `false` when the tenant has no resource with this id. */
+  delete(type: ScimResourceType, tenant: string, id: string): Promise<Result<boolean>>;
 }
-/** TXT lookups over DNS-over-HTTPS (the `application/dns-json` API). */
-export declare function dohResolver(options?: DohResolverOptions): TxtResolver;
-interface SsoAuthAdmin {
-  /** The project URL (`SUPABASE_URL`). */
-  readonly url: string;
-  /** A secret or service-role key. Server-only. */
-  readonly secretKey: string;
-  readonly fetch?: typeof fetch;
+interface SqlScimStoreOptions {
+  readonly schema?: string | undefined;
 }
-interface SsoAdminOptions extends BlockTemporalOptions {
-  /** A service-role transport: these functions are granted to `service_role` only. */
-  readonly transport: BlockTransport;
-  /** Supabase Auth's admin API, for SAML providers. */
-  readonly auth?: SsoAuthAdmin;
-  /** TXT lookups for `verifyDomain`. Default `dohResolver()`. */
-  readonly resolver?: TxtResolver;
-  readonly schema?: string;
-  readonly mappers?: readonly ErrorMapper[];
-}
-/** Who asked, so the database checks `sso.manage`; omit for app-owned calls. */
-interface SsoActor {
-  readonly actorId?: string;
+/**
+ * The SCIM store over the sso module's `scim_*` functions. Needs a
+ * service-role transport. It keeps the core attributes only, so extension
+ * attributes are not stored; the handler leaves the filter and paging to
+ * itself.
+ */
+export declare function sqlScimStore(transport: BlockTransport, options?: SqlScimStoreOptions): ScimStore;
+type ScimSyncOperation = "create" | "replace" | "patch" | "delete";
+/** One SCIM write, as the sync log records it. */
+interface ScimSyncEntry {
+  readonly tenant: string;
+  readonly operation: ScimSyncOperation;
+  readonly resourceType: ScimResourceType;
+  /** `undefined` for a create that failed. */
+  readonly resourceId: string | undefined;
+  /** The HTTP status the handler answered. */
+  readonly status: number;
+  /** The SCIM `detail` of a failed write. */
+  readonly error: string | undefined;
+  readonly requestId: string | undefined;
 }
-type SamlMetadata = {
-  readonly metadataUrl: string;
-  readonly metadataXml?: never;
-} | {
-  readonly metadataXml: string;
-  readonly metadataUrl?: never;
-};
-type SamlProviderInput = SamlMetadata & {
-  /** Verified domains of the organization whose users sign in with this provider. */
-  readonly domains: readonly string[];
-  /** Supabase Auth's `attribute_mapping`, such as `{ keys: { email: { name: "mail" } } }`. */
-  readonly attributeMapping?: Readonly<Record<string, unknown>>;
-  readonly nameIdFormat?: string;
-};
-interface SsoAdmin {
-  /** Looks up the domain's TXT record and marks it verified when the token is there. */
-  verifyDomain(domainId: string, options?: SsoActor & {
-    readonly signal?: AbortSignal;
-  }): AsyncResult<OrganizationDomain>;
-  /** Creates a SAML provider in Supabase Auth and records it for the organization. */
-  addSamlProvider(organizationId: string, input: SamlProviderInput, options?: SsoActor): AsyncResult<SsoProvider>;
-  updateSamlProvider(providerId: string, input: Partial<SamlProviderInput> & {
-    readonly domains: readonly string[];
-  }, options?: SsoActor): AsyncResult<SsoProvider>;
-  /** Deletes the provider from Supabase Auth; `undefined` when the organization has no such provider. */
-  removeSamlProvider(providerId: string, options?: SsoActor): AsyncResult<SsoProvider | undefined>;
+/**
+ * Records SCIM writes. The handler waits for `record` but ignores its
+ * failures, so a log can never change an answer.
+ */
+interface ScimSyncLog {
+  readonly apiVersion: 1;
+  record(entry: ScimSyncEntry): Promise<unknown>;
 }
-/** Domain verification and SAML providers with a service-role client. */
-export declare function createSsoAdmin(options: SsoAdminOptions): SsoAdmin;
+/**
+ * The sync log over `scim_sync_log` (`blocks.sso.options.syncLog`). Needs a
+ * service-role transport.
+ */
+export declare function sqlScimSyncLog(transport: BlockTransport, options?: SqlScimStoreOptions): ScimSyncLog;
 //#endregion
 //#region src/blocks/sso/scim.d.ts
-interface ScimHandlerOptions extends BlockTemporalOptions {
-  /** A service-role transport: the SCIM functions are granted to `service_role` only. */
-  readonly transport: BlockTransport;
+interface ScimHandlerBaseOptions extends BlockTemporalOptions {
   /** Verifies the bearer token: an organization API key with the `scim` scope. */
   readonly keys: Pick<ApiKeys, "verify">;
   /** The path the handler is mounted at, such as `/scim/v2`. Default empty. */
@@ -136,8 +148,24 @@ interface ScimHandlerOptions extends BlockTemporalOptions {
   /** Page size and the largest `count`. Default 100. */
   readonly maxResults?: number;
   readonly documentationUri?: string;
+  /** The schema of the `scim_*` functions, with `transport`. */
   readonly schema?: string;
+  /** Records each write; `sqlScimSyncLog` writes `scim_sync_log`. */
+  readonly log?: ScimSyncLog;
+  /** The request id the log records. Default the `x-request-id` header. */
+  readonly requestId?: (request: Request) => string | undefined;
 }
+/**
+ * Where users and groups live: a `store`, or a service-role `transport` for
+ * `sqlScimStore` (the SCIM functions are granted to `service_role` only).
+ */
+type ScimHandlerOptions = ScimHandlerBaseOptions & ({
+  readonly store: ScimStore;
+  readonly transport?: never;
+} | {
+  readonly transport: BlockTransport;
+  readonly store?: never;
+});
 /**
  * A SCIM 2.0 service provider (RFC 7644) as a web handler: `/Users` and
  * `/Groups` with filters, PATCH and ETags, plus the discovery endpoints.
@@ -146,36 +174,6 @@ interface ScimHandlerOptions extends BlockTemporalOptions {
  */
 export declare function scimHandler(options: ScimHandlerOptions): (request: Request) => Promise<Response>;
 //#endregion
-//#region src/blocks/sso/scim-filter.d.ts
-type CompareOp = "eq" | "ne" | "co" | "sw" | "ew" | "gt" | "ge" | "lt" | "le";
-type ScimFilter = {
-  readonly op: "and" | "or";
-  readonly left: ScimFilter;
-  readonly right: ScimFilter;
-} | {
-  readonly op: "not";
-  readonly filter: ScimFilter;
-} | {
-  readonly op: "pr";
-  readonly path: string;
-} | {
-  readonly op: CompareOp;
-  readonly path: string;
-  readonly value: string | number | boolean | null;
-} | {
-  readonly op: "value";
-  readonly path: string;
-  readonly filter: ScimFilter;
-};
-/** A filter the service provider can't parse or apply: 400 `invalidFilter`. */
-export declare class ScimFilterError extends Error {
-  override readonly name = "ScimFilterError";
-}
-/** Parses a SCIM filter; throws `ScimFilterError`. */
-declare function parseFilter(input: string): ScimFilter;
-/** Whether `resource` matches; a multi-valued attribute matches when any value does. */
-declare function matches(resource: Record<string, unknown>, filter: ScimFilter): boolean;
-//#endregion
 //#region src/blocks/sso/scim-schema.d.ts
 /** SCIM 2.0 schema URIs and the attributes this service provider supports (RFC 7643). */
 export declare const SCIM_USER = "urn:ietf:params:scim:schemas:core:2.0:User";
@@ -195,4 +193,28 @@ interface ScimAttribute {
   readonly subAttributes?: readonly ScimAttribute[];
 }
 //#endregion
-export { type BlockTransport, type DohResolverOptions, type DomainRecord, type OrganizationDomain, type SamlMetadata, type SamlProviderInput, type ScimAttribute, type ScimFilter, type ScimHandlerOptions, type Sso, type SsoActor, type SsoAdmin, type SsoAdminOptions, type SsoAuthAdmin, type SsoDomain, type SsoOptions, type SsoProvider, type TxtResolver, dbTransport, matches as matchesScimFilter, parseFilter as parseScimFilter, rpcTransport, sqlTransport };
+//#region src/blocks/sso/events.d.ts
+/** The events of the `sso` block: type to data. */
+type SsoEvents = {
+  readonly "organization.member_added": OrganizationEventData;
+  readonly "organization.member_removed": OrganizationEventData;
+  readonly "organization.role_changed": OrganizationEventData;
+  readonly "organization.domain_added": OrganizationDomainEventData;
+  readonly "organization.domain_updated": OrganizationDomainEventData;
+  readonly "organization.domain_verified": OrganizationDomainEventData;
+  readonly "organization.domain_removed": OrganizationDomainEventData;
+  readonly "sso_provider.registered": SsoProviderEventData;
+  readonly "sso_provider.unregistered": SsoProviderEventData;
+  readonly "scim_user.saved": ScimEventData;
+  readonly "scim_user.deleted": ScimEventData;
+  readonly "scim_group.saved": ScimEventData;
+  readonly "scim_group.deleted": ScimEventData;
+};
+/** The `sso` block's event types, for its manifest and `onBlockEvent`. */
+export declare const ssoEvents: Events<SsoEvents>;
+//#endregion
+//#region src/blocks/sso/manifest.d.ts
+/** The `sso` block's manifest (ADR 0029). */
+export declare const ssoBlock: BlockOf<"sso", typeof createSso, SsoEvents>;
+//#endregion
+export { type BlockTransport, type DohResolverOptions, type DomainRecord, type OrganizationDomain, type SamlMetadata, type SamlProviderInput, type ScimAttribute, type ScimFilter, type ScimHandlerOptions, type ScimListPage, type ScimListQuery, type ScimResourceType, type ScimSaveInput, type ScimStore, type ScimStoredResource, type ScimSyncEntry, type ScimSyncLog, type ScimSyncOperation, type SqlScimStoreOptions, type Sso, type SsoActor, type SsoAdmin, type SsoAdminOptions, type SsoAuthAdmin, type SsoDomain, type SsoEvents, type SsoOptions, type SsoProvider, type TxtResolver, createSso, createSsoAdmin, dbTransport, dohResolver, matches as matchesScimFilter, parseFilter as parseScimFilter, rpcTransport, sqlTransport };