@flow-industries/id 0.26.5 → 0.27.0

package/dist/sdk/types/auth.d.ts

@@ -1,6 +1,7 @@
 import type { JWTPayload } from "jose";
 import type { AuthEventName } from "./events";
 import type { ManagedPdsEnrollment } from "./managed-provisioning";
+import type { OAuthProviderSummary } from "./oauth";
 export type FlowUser = {
     id: string;
     username: string;
@@ -77,6 +78,8 @@ export type AuthResponse = {
 export type AuthConfig = {
     managedPdsEnabled?: boolean;
     atprotoEnabled?: boolean;
+    /** Enabled generic OAuth providers, sign-in and connect-only alike. */
+    oauthProviders?: OAuthProviderSummary[];
     rpId: string;
     rpName: string;
 };

package/dist/sdk/types/github-connector.d.ts

@@ -0,0 +1,88 @@
+import type { Context } from "hono";
+import type { z } from "zod";
+import type { githubOperations } from "../github/operations";
+import type { GitHubScope } from "../github/scopes";
+import type { RawRecord, RawValue } from "../json";
+import type { OAuthCredential } from "./oauth";
+export type { GitHubScope };
+export type GitHubOperations = typeof githubOperations;
+export type GitHubOperationId = keyof GitHubOperations;
+export type GitHubOperationInput<Id extends GitHubOperationId> = z.input<GitHubOperations[Id]["input"]>;
+export type GitHubOperationData<Id extends GitHubOperationId> = z.output<GitHubOperations[Id]["response"]>;
+/** A connector success: the projected GitHub payload and, for paginated
+ * operations, the `page` to ask for next (null on the last page). */
+export type GitHubConnectorResult<Id extends GitHubOperationId> = {
+    data: GitHubOperationData<Id>;
+    nextPage: number | null;
+};
+export type GitHubConnectorErrorCode = "GITHUB_CONNECTOR_DISABLED" | "ORIGIN_DENIED" | "SIGN_IN_REQUIRED" | "ACCOUNT_CHANGED" | "RATE_LIMITED" | "UNKNOWN_OPERATION" | "INVALID_BODY" | "TOO_LARGE" | "GITHUB_NOT_CONNECTED" | "GITHUB_RECONNECT_REQUIRED" | "GITHUB_SCOPE_REQUIRED" | "GITHUB_RATE_LIMITED" | "GITHUB_NOT_FOUND" | "GITHUB_FORBIDDEN" | "GITHUB_CONFLICT" | "GITHUB_VALIDATION_FAILED" | "GITHUB_UNAVAILABLE" | "GITHUB_INVALID_RESPONSE" | "CONNECTOR_UNAVAILABLE";
+/** The connector's refusal body. `consentUrl` is the Flow ID page that
+ * connects GitHub or grants `requiredScopes`; `retryAfter` is in seconds. */
+export type GitHubConnectorFailure = {
+    code: GitHubConnectorErrorCode;
+    requiredScopes?: GitHubScope[];
+    consentUrl?: string;
+    retryAfter?: number;
+    fields?: string[];
+};
+export type GitHubUpstreamRequest = {
+    method: "GET" | "POST" | "PATCH" | "PUT";
+    segments: readonly string[];
+    query?: Readonly<Record<string, string | undefined>>;
+    body?: RawRecord;
+};
+/** A validated operation call, with its schema-specific parts erased so the
+ * route can drive every operation through one code path. */
+export type GitHubOperationPlan = {
+    ok: true;
+    request: GitHubUpstreamRequest;
+    scopes: readonly GitHubScope[];
+    repository: boolean;
+    paginated: boolean;
+    parse: (body: RawValue) => {
+        ok: true;
+        data: unknown;
+    } | {
+        ok: false;
+    };
+} | {
+    ok: false;
+    fields: string[];
+};
+export type GitHubConnectorCaller = {
+    user: {
+        id: string;
+        isGuest?: boolean;
+    };
+    /** The Flow audience the caller's session or access token is bound to. */
+    audience: string;
+};
+export type GitHubConnectorDeps = {
+    enabled: boolean;
+    audienceAllowed: (audience: string) => boolean;
+    resolveCaller: (context: Context) => Promise<GitHubConnectorCaller | null>;
+    admit: (userId: string) => Promise<boolean>;
+    resolveGitHubCredential: (userId: string) => Promise<OAuthCredential | null>;
+    /** Drops a grant GitHub rejected, unless a newer one already replaced it,
+     * so the account page offers Reconnect instead of showing it connected. */
+    discardGitHubCredential: (credential: OAuthCredential) => Promise<void>;
+    consentUrl: (scopes: readonly GitHubScope[]) => string;
+    fetch: (input: URL, init: RequestInit) => Promise<Response>;
+    now: () => number;
+};
+export type GitHubConnectorCallOptions = {
+    signal?: AbortSignal;
+};
+/** The SDK's GitHub connector: Flow ID calls GitHub with the user's stored
+ * grant, so the app never holds a GitHub token. */
+export type GitHubConnector = {
+    call<Id extends GitHubOperationId>(operation: Id, input: GitHubOperationInput<Id>, options?: GitHubConnectorCallOptions): Promise<GitHubConnectorResult<Id>>;
+    /** The Flow ID page that connects GitHub or adds `scopes` to the grant. */
+    consentUrl(scopes?: readonly GitHubScope[]): string;
+    /** Opens {@link GitHubConnector.consentUrl} in a new window; null when the
+     * browser blocked it or there is no window to open from. */
+    requestScopes(scopes?: readonly GitHubScope[]): Window | null;
+};
+export type GitHubConnectorOptions = {
+    fetch?: (input: string, init: RequestInit) => Promise<Response>;
+};

package/dist/sdk/types/index.d.ts

@@ -11,13 +11,15 @@ export type { AuthErrorCode, AuthEventName, AuthEventRecord, AuthMode, AuthOutco
 export type { ActiveAction, CatalogFieldRef, ClockAnchor, FinishedSummary, FocusApi, FocusPhase, FocusSessionEvent, FocusSessionState, StartFocusRequest, StudySearchHit, } from "./focus";
 export type { GameEventReport, GameLifecycleEventName, GameLifecycleFeedEvent, GameLifecycleFeedPage, GamePlayerSession, } from "./game";
 export { GAME_LIFECYCLE_EVENT_NAMES } from "./game";
+export type { GitHubConnector, GitHubConnectorCaller, GitHubConnectorCallOptions, GitHubConnectorDeps, GitHubConnectorErrorCode, GitHubConnectorFailure, GitHubConnectorOptions, GitHubConnectorResult, GitHubOperationData, GitHubOperationId, GitHubOperationInput, GitHubOperationPlan, GitHubOperations, GitHubScope, GitHubUpstreamRequest, } from "./github-connector";
 export type { HostedOAuthMapping, HostedOAuthMappingReader, HostedOAuthProofOptions, HostedOAuthTransaction, } from "./hosted-oauth";
 export type { HostingQuotaAdmission, HostingQuotaLedger, HostingQuotaPolicy, HostingQuotaReservation, } from "./hosting-quota";
-export type { AccountProfileData } from "./landing";
+export type { AccountProfileData, OAuthConnectionState } from "./landing";
 export type * from "./managed-provisioning";
 export type { Bridge, BridgeParameters, FlowAccount, FlowRemote, FlowRemoteConfig, FromWindowOptions, MessageResponse, Messenger, OneOf, Payload, QueuedRequest, ReadyOptions, RemoteFlowState, RemoteState, Schema, Storage, Topic, WithReady, } from "./messenger";
 export type { NoteBlob, NoteCollection, NoteOperation, NoteRecord, NoteResponses, NoteStoredRecord, NoteTransportDeps, NoteVaultHeader, } from "./note-transport";
 export type { MarkNotificationsReadInput, NotificationCounts, NotificationEntry, NotificationPage, NotificationReadResult, NotificationRefusal, } from "./notifications";
+export type { OAuthCompletion, OAuthConnectionStatus, OAuthCredential, OAuthProfile, OAuthProviderSummary, OAuthStartRequest, OAuthStartResponse, OAuthStatus, } from "./oauth";
 export type { OtpVerificationFailure, OtpVerificationResult, VerificationAdapter, } from "./otp";
 export type { Call, ConnectCapabilities, ConnectResponse, MethodName, MethodParams, MethodResult, RestoreResponse, RpcRequest, SendCallsParams, SendCallsRequest, SendCallsResponse, SendTransactionParams, SendTransactionRequest, SendTransactionResponse, SignMessageRequest, SignMessageResponse, SignTypedDataRequest, SignTypedDataResponse, TransactionArgs, TypedData, TypedDataDomain, TypedDataField, } from "./protocol";
 export { isPersonalSignParams, isSendCallsParams, isSendTransactionParams, } from "./protocol";

package/dist/sdk/types/landing.d.ts

@@ -1,4 +1,5 @@
 import type { FlowUser } from "./auth";
+import type { OAuthStatus } from "./oauth";
 export type AccountProfileData = FlowUser & {
     bio?: string | null;
     email?: string | null;
@@ -8,3 +9,22 @@ export type AccountProfileData = FlowUser & {
     image?: string | null;
     walletAddress?: string | null;
 };
+/** One provider's account-page connection, as the shared hook drives it. */
+export type OAuthConnectionState = {
+    status: OAuthStatus | null;
+    connection: OAuthStatus["connection"];
+    connected: boolean;
+    /** The provider account the row names, once one is linked. */
+    detail: string | null;
+    statusText: string | null;
+    /** Why disconnecting is blocked, with the id the disabled button points at. */
+    blockedHint: {
+        id: string;
+        text: string;
+    } | null;
+    pending: boolean;
+    error: string | null;
+    /** Leaves for the provider; extra `scopes` are added to those already granted. */
+    connect(scopes?: string[]): Promise<void>;
+    unlink(): Promise<void>;
+};

package/dist/sdk/types/oauth.d.ts

@@ -0,0 +1,64 @@
+/** A provider token held server-side for one external account; never sent to a browser. */
+export type OAuthCredential = {
+    accessToken: string;
+    refreshToken?: string;
+    /** Epoch milliseconds; absent when the provider issues non-expiring tokens. */
+    expiresAt?: number;
+    scopes: string[];
+    tokenType: string;
+    /** The provider's stable subject, equal to `account.accountId`. */
+    subject: string;
+};
+/** What a provider's `profile()` mapper extracts from its token and userinfo responses. */
+export type OAuthProfile = {
+    subject: string;
+    displayName?: string | null;
+    usernameHint?: string | null;
+    email?: string | null;
+    emailVerified?: boolean;
+};
+/** An enabled generic provider as the hosted page and account page see it. */
+export type OAuthProviderSummary = {
+    id: string;
+    displayName: string;
+    /** False for connect-only providers, which never count as a sign-in method. */
+    signIn: boolean;
+};
+export type OAuthStartRequest = {
+    intent: "login" | "link";
+    transaction?: string;
+    expectedUserId?: string;
+    invitationCode?: string;
+    /** Extra scopes from the provider's requestable set, unioned with granted ones. */
+    scopes?: string[];
+};
+export type OAuthStartResponse = {
+    url: string;
+    completionToken: string;
+};
+export type OAuthCompletion = {
+    user: {
+        id: string;
+        username: string;
+        isGuest: false;
+    };
+} | {
+    linked: true;
+};
+export type OAuthConnectionStatus = "connected" | "reconnect_required";
+export type OAuthStatus = {
+    provider: string;
+    displayName: string;
+    enabled: boolean;
+    signIn: boolean;
+    connection: {
+        accountId: string;
+        displayName: string | null;
+        status: OAuthConnectionStatus;
+        /** Granted scopes for providers that keep a credential; empty otherwise. */
+        scopes: string[];
+    } | null;
+    requestableScopes: string[];
+    canUnlink: boolean;
+    unlinkBlockReason: string | null;
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flow-industries/id",
-  "version": "0.26.5",
+  "version": "0.27.0",
   "license": "MIT",
   "repository": {
     "type": "git",