@draftlab/auth 0.15.0 → 0.15.1

package/dist/client.d.mts

@@ -3,7 +3,6 @@ import { SubjectSchema } from "./subject.mjs";
 import { StandardSchemaV1 } from "@standard-schema/spec";
 
 //#region src/client.d.ts
-
 /**
  * Result type for operations that can succeed or fail.
  *
@@ -38,16 +37,16 @@ type FetchLike = (url: string, init?: RequestInit) => Promise<FetchResponse>;
  */
 interface WellKnown {
   /**
-   * URI to the JWKS endpoint for token verification.
-   */
+       * URI to the JWKS endpoint for token verification.
+       */
   jwks_uri: string;
   /**
-   * URI to the token endpoint for authorization code exchange.
-   */
+       * URI to the token endpoint for authorization code exchange.
+       */
   token_endpoint: string;
   /**
-   * URI to the authorization endpoint for starting flows.
-   */
+       * URI to the authorization endpoint for starting flows.
+       */
   authorization_endpoint: string;
 }
 /**
@@ -55,16 +54,16 @@ interface WellKnown {
  */
 interface Tokens {
   /**
-   * Access token for making authenticated API requests.
-   */
+       * Access token for making authenticated API requests.
+       */
   access: string;
   /**
-   * Refresh token for obtaining new access tokens.
-   */
+       * Refresh token for obtaining new access tokens.
+       */
   refresh: string;
   /**
-   * Number of seconds until the access token expires.
-   */
+       * Number of seconds until the access token expires.
+       */
   expiresIn: number;
 }
 /**
@@ -72,12 +71,12 @@ interface Tokens {
  */
 type Challenge = {
   /**
-   * State parameter for CSRF protection.
-   */
+       * State parameter for CSRF protection.
+       */
   state: string;
   /**
-   * PKCE code verifier for token exchange.
-   */
+       * PKCE code verifier for token exchange.
+       */
   verifier?: string;
 };
 /**
@@ -85,37 +84,37 @@ type Challenge = {
  */
 interface ClientInput {
   /**
-   * Client ID that identifies your application.
-   *
-   * @example
-   * ```ts
-   * {
-   *   clientID: "my-web-app"
-   * }
-   * ```
-   */
+       * Client ID that identifies your application.
+       *
+       * @example
+       * ```ts
+       * {
+       *   clientID: "my-web-app"
+       * }
+       * ```
+       */
   clientID: string;
   /**
-   * Base URL of your Draft Auth server.
-   *
-   * @example
-   * ```ts
-   * {
-   *   issuer: "https://auth.myserver.com"
-   * }
-   * ```
-   */
+       * Base URL of your Draft Auth server.
+       *
+       * @example
+       * ```ts
+       * {
+       *   issuer: "https://auth.myserver.com"
+       * }
+       * ```
+       */
   issuer: string;
   /**
-   * Optionally, override the internally used fetch function.
-   *
-   * @example
-   * ```ts
-   * {
-   *   fetch: customFetch
-   * }
-   * ```
-   */
+       * Optionally, override the internally used fetch function.
+       *
+       * @example
+       * ```ts
+       * {
+       *   fetch: customFetch
+       * }
+       * ```
+       */
   fetch?: FetchLike;
 }
 /**
@@ -123,32 +122,32 @@ interface ClientInput {
  */
 interface AuthorizeOptions {
   /**
-   * Enable PKCE flow for enhanced security.
-   *
-   * Recommended for single-page applications and mobile apps.
-   *
-   * @default false
-   * @example
-   * ```ts
-   * {
-   *   pkce: true
-   * }
-   * ```
-   */
+       * Enable PKCE flow for enhanced security.
+       *
+       * Recommended for single-page applications and mobile apps.
+       *
+       * @default false
+       * @example
+       * ```ts
+       * {
+       *   pkce: true
+       * }
+       * ```
+       */
   pkce?: boolean;
   /**
-   * Specific authentication provider to use.
-   *
-   * If not specified, users see a provider selection screen
-   * or are redirected to the single configured provider.
-   *
-   * @example
-   * ```ts
-   * {
-   *   provider: "google"
-   * }
-   * ```
-   */
+       * Specific authentication provider to use.
+       *
+       * If not specified, users see a provider selection screen
+       * or are redirected to the single configured provider.
+       *
+       * @example
+       * ```ts
+       * {
+       *   provider: "google"
+       * }
+       * ```
+       */
   provider?: string;
 }
 /**
@@ -156,24 +155,24 @@ interface AuthorizeOptions {
  */
 interface AuthorizeResult {
   /**
-   * Challenge data needed for PKCE flows.
-   *
-   * Store this securely and use when exchanging the code.
-   *
-   * @example
-   * ```ts
-   * sessionStorage.setItem("challenge", JSON.stringify(challenge))
-   * ```
-   */
+       * Challenge data needed for PKCE flows.
+       *
+       * Store this securely and use when exchanging the code.
+       *
+       * @example
+       * ```ts
+       * sessionStorage.setItem("challenge", JSON.stringify(challenge))
+       * ```
+       */
   challenge: Challenge;
   /**
-   * Authorization URL to redirect the user to.
-   *
-   * @example
-   * ```ts
-   * window.location.href = url
-   * ```
-   */
+       * Authorization URL to redirect the user to.
+       *
+       * @example
+       * ```ts
+       * window.location.href = url
+       * ```
+       */
   url: string;
 }
 /**
@@ -181,17 +180,17 @@ interface AuthorizeResult {
  */
 interface RefreshOptions {
   /**
-   * Current access token to check before refreshing.
-   *
-   * Helps avoid unnecessary refresh requests.
-   *
-   * @example
-   * ```ts
-   * {
-   *   access: currentAccessToken
-   * }
-   * ```
-   */
+       * Current access token to check before refreshing.
+       *
+       * Helps avoid unnecessary refresh requests.
+       *
+       * @example
+       * ```ts
+       * {
+       *   access: currentAccessToken
+       * }
+       * ```
+       */
   access?: string;
 }
 /**
@@ -199,34 +198,34 @@ interface RefreshOptions {
  */
 interface VerifyOptions {
   /**
-   * Refresh token for automatic refresh if access token is expired.
-   *
-   * If passed in, this will automatically refresh the access token if it has expired.
-   *
-   * @example
-   * ```ts
-   * {
-   *   refresh: refreshToken
-   * }
-   * ```
-   */
+       * Refresh token for automatic refresh if access token is expired.
+       *
+       * If passed in, this will automatically refresh the access token if it has expired.
+       *
+       * @example
+       * ```ts
+       * {
+       *   refresh: refreshToken
+       * }
+       * ```
+       */
   refresh?: string;
   /**
-   * Expected issuer for validation.
-   * @internal
-   */
+       * Expected issuer for validation.
+       * @internal
+       */
   issuer?: string;
   /**
-   * Expected audience for validation.
-   * Defaults to clientID for security. Override only if you know what you're doing.
-   * @internal
-   */
+       * Expected audience for validation.
+       * Defaults to clientID for security. Override only if you know what you're doing.
+       * @internal
+       */
   audience?: string;
   /**
-   * Custom fetch for HTTP requests.
-   *
-   * Optionally, override the internally used fetch function.
-   */
+       * Custom fetch for HTTP requests.
+       *
+       * Optionally, override the internally used fetch function.
+       */
   fetch?: FetchLike;
 }
 /**
@@ -234,19 +233,26 @@ interface VerifyOptions {
  */
 interface VerifyResult<T extends SubjectSchema> {
   /**
-   * New tokens if access token was refreshed during verification.
-   */
+       * New tokens if access token was refreshed during verification.
+       */
   tokens?: Tokens;
   /**
-   * Audience (client ID) the token was issued for.
-   * @internal
-   */
+       * Audience (client ID) the token was issued for.
+       * @internal
+       */
   aud: string;
   /**
-   * Decoded subject information from the access token.
-   *
-   * Contains user data that was encoded when the token was issued.
-   */
+       * Unique subject identifier.
+       *
+       * This is a stable, consistent identifier derived from the subject type and properties.
+       * Format: `{type}:{hash}` (e.g., `user:30e16a2659c8bbb2`)
+       */
+  sub: string;
+  /**
+       * Decoded subject information from the access token.
+       *
+       * Contains user data that was encoded when the token was issued.
+       */
   subject: { [K in keyof T]: {
     type: K;
     properties: StandardSchemaV1.InferOutput<T[K]>;
@@ -257,18 +263,18 @@ interface VerifyResult<T extends SubjectSchema> {
  */
 interface RevokeOptions {
   /**
-   * Optional hint about the token type.
-   * Can be "access_token" or "refresh_token".
-   *
-   * Helps the server optimize token lookup.
-   *
-   * @example
-   * ```ts
-   * {
-   *   tokenTypeHint: "refresh_token"
-   * }
-   * ```
-   */
+       * Optional hint about the token type.
+       * Can be "access_token" or "refresh_token".
+       *
+       * Helps the server optimize token lookup.
+       *
+       * @example
+       * ```ts
+       * {
+       *   tokenTypeHint: "refresh_token"
+       * }
+       * ```
+       */
   tokenTypeHint?: "access_token" | "refresh_token";
 }
 /**
@@ -276,165 +282,165 @@ interface RevokeOptions {
  */
 interface Client {
   /**
-   * Start an OAuth authorization flow.
-   *
-   * @param redirectURI - Where users will be sent after authorization
-   * @param response - Response type ("code" or "token")
-   * @param opts - Additional authorization options
-   * @returns Authorization URL and challenge data
-   *
-   * @example Basic flow
-   * ```ts
-   * const result = await client.authorize(
-   *   "https://myapp.com/callback",
-   *   "code"
-   * )
-   * if (result.success) {
-   *   window.location.href = result.data.url
-   * }
-   * ```
-   *
-   * @example PKCE flow
-   * ```ts
-   * const result = await client.authorize(
-   *   "https://spa.example.com/callback",
-   *   "code",
-   *   { pkce: true, scopes: ["read", "write"] }
-   * )
-   * if (result.success) {
-   *   sessionStorage.setItem("challenge", JSON.stringify(result.data.challenge))
-   *   window.location.href = result.data.url
-   * }
-   * ```
-   */
+       * Start an OAuth authorization flow.
+       *
+       * @param redirectURI - Where users will be sent after authorization
+       * @param response - Response type ("code" or "token")
+       * @param opts - Additional authorization options
+       * @returns Authorization URL and challenge data
+       *
+       * @example Basic flow
+       * ```ts
+       * const result = await client.authorize(
+       *   "https://myapp.com/callback",
+       *   "code"
+       * )
+       * if (result.success) {
+       *   window.location.href = result.data.url
+       * }
+       * ```
+       *
+       * @example PKCE flow
+       * ```ts
+       * const result = await client.authorize(
+       *   "https://spa.example.com/callback",
+       *   "code",
+       *   { pkce: true, scopes: ["read", "write"] }
+       * )
+       * if (result.success) {
+       *   sessionStorage.setItem("challenge", JSON.stringify(result.data.challenge))
+       *   window.location.href = result.data.url
+       * }
+       * ```
+       */
   authorize(redirectURI: string, response: "code" | "token", opts?: AuthorizeOptions): Promise<Result<AuthorizeResult>>;
   /**
-   * Exchange authorization code for tokens.
-   *
-   * @param code - Authorization code from the callback
-   * @param redirectURI - Same redirect URI used in authorization
-   * @param verifier - PKCE code verifier (required for PKCE flows)
-   * @returns Access tokens and metadata
-   *
-   * @example Basic exchange
-   * ```ts
-   * const urlParams = new URLSearchParams(window.location.search)
-   * const code = urlParams.get('code')
-   *
-   * if (code) {
-   *   const result = await client.exchange(code, "https://myapp.com/callback")
-   *   if (result.success) {
-   *     const { access, refresh } = result.data
-   *     // Store tokens securely
-   *   }
-   * }
-   * ```
-   *
-   * @example PKCE exchange
-   * ```ts
-   * const challenge = JSON.parse(sessionStorage.getItem("challenge") || "{}")
-   * const code = new URLSearchParams(window.location.search).get('code')
-   *
-   * if (code && challenge.verifier) {
-   *   const result = await client.exchange(
-   *     code,
-   *     "https://spa.example.com/callback",
-   *     challenge.verifier
-   *   )
-   *   if (result.success) {
-   *     sessionStorage.removeItem("challenge")
-   *     // Handle tokens
-   *   }
-   * }
-   * ```
-   */
+       * Exchange authorization code for tokens.
+       *
+       * @param code - Authorization code from the callback
+       * @param redirectURI - Same redirect URI used in authorization
+       * @param verifier - PKCE code verifier (required for PKCE flows)
+       * @returns Access tokens and metadata
+       *
+       * @example Basic exchange
+       * ```ts
+       * const urlParams = new URLSearchParams(window.location.search)
+       * const code = urlParams.get('code')
+       *
+       * if (code) {
+       *   const result = await client.exchange(code, "https://myapp.com/callback")
+       *   if (result.success) {
+       *     const { access, refresh } = result.data
+       *     // Store tokens securely
+       *   }
+       * }
+       * ```
+       *
+       * @example PKCE exchange
+       * ```ts
+       * const challenge = JSON.parse(sessionStorage.getItem("challenge") || "{}")
+       * const code = new URLSearchParams(window.location.search).get('code')
+       *
+       * if (code && challenge.verifier) {
+       *   const result = await client.exchange(
+       *     code,
+       *     "https://spa.example.com/callback",
+       *     challenge.verifier
+       *   )
+       *   if (result.success) {
+       *     sessionStorage.removeItem("challenge")
+       *     // Handle tokens
+       *   }
+       * }
+       * ```
+       */
   exchange(code: string, redirectURI: string, verifier?: string): Promise<Result<Tokens, InvalidAuthorizationCodeError>>;
   /**
-   * Refresh an access token using a refresh token.
-   *
-   * @param refresh - Refresh token to use
-   * @param opts - Additional refresh options
-   * @returns New tokens if refresh was needed
-   *
-   * @example Basic refresh
-   * ```ts
-   * const result = await client.refresh(storedRefreshToken)
-   *
-   * if (result.success && result.data.tokens) {
-   *   const { access, refresh: newRefresh } = result.data.tokens
-   *   updateStoredTokens(access, newRefresh)
-   * } else if (result.success) {
-   *   // Token still valid
-   * } else {
-   *   redirectToLogin()
-   * }
-   * ```
-   */
+       * Refresh an access token using a refresh token.
+       *
+       * @param refresh - Refresh token to use
+       * @param opts - Additional refresh options
+       * @returns New tokens if refresh was needed
+       *
+       * @example Basic refresh
+       * ```ts
+       * const result = await client.refresh(storedRefreshToken)
+       *
+       * if (result.success && result.data.tokens) {
+       *   const { access, refresh: newRefresh } = result.data.tokens
+       *   updateStoredTokens(access, newRefresh)
+       * } else if (result.success) {
+       *   // Token still valid
+       * } else {
+       *   redirectToLogin()
+       * }
+       * ```
+       */
   refresh(refresh: string, opts?: RefreshOptions): Promise<Result<{
     tokens?: Tokens;
   }, InvalidRefreshTokenError | InvalidAccessTokenError>>;
   /**
-   * Verify and decode an access token.
-   *
-   * @param subjects - Subject schema used when creating the issuer
-   * @param token - Access token to verify
-   * @param options - Additional verification options
-   * @returns Decoded token data and user information
-   *
-   * @example Basic verification
-   * ```ts
-   * const result = await client.verify(subjects, accessToken)
-   *
-   * if (result.success) {
-   *   const { subject, scopes } = result.data
-   *   // Access user ID: subject.properties.userID
-   *   // Access scopes: scopes?.join(', ')
-   * }
-   * ```
-   *
-   * @example With automatic refresh
-   * ```ts
-   * const result = await client.verify(subjects, accessToken, {
-   *   refresh: refreshToken
-   * })
-   *
-   * if (result.success) {
-   *   if (result.data.tokens) {
-   *     // Tokens were refreshed
-   *     updateStoredTokens(result.data.tokens.access, result.data.tokens.refresh)
-   *   }
-   *   // Use verified subject data
-   *   const user = result.data.subject.properties
-   * }
-   * ```
-   */
+       * Verify and decode an access token.
+       *
+       * @param subjects - Subject schema used when creating the issuer
+       * @param token - Access token to verify
+       * @param options - Additional verification options
+       * @returns Decoded token data and user information
+       *
+       * @example Basic verification
+       * ```ts
+       * const result = await client.verify(subjects, accessToken)
+       *
+       * if (result.success) {
+       *   const { subject, scopes } = result.data
+       *   // Access user ID: subject.properties.userID
+       *   // Access scopes: scopes?.join(', ')
+       * }
+       * ```
+       *
+       * @example With automatic refresh
+       * ```ts
+       * const result = await client.verify(subjects, accessToken, {
+       *   refresh: refreshToken
+       * })
+       *
+       * if (result.success) {
+       *   if (result.data.tokens) {
+       *     // Tokens were refreshed
+       *     updateStoredTokens(result.data.tokens.access, result.data.tokens.refresh)
+       *   }
+       *   // Use verified subject data
+       *   const user = result.data.subject.properties
+       * }
+       * ```
+       */
   verify<T extends SubjectSchema>(subjects: T, token: string, options?: VerifyOptions): Promise<Result<VerifyResult<T>, InvalidRefreshTokenError | InvalidAccessTokenError | InvalidSubjectError>>;
   /**
-   * Revoke a token (access or refresh token).
-   *
-   * Once revoked, the token cannot be used to access resources or refresh.
-   * Useful for implementing logout functionality.
-   *
-   * @param token - The token to revoke
-   * @param opts - Additional revocation options
-   * @returns Empty result on success
-   *
-   * @example Logout with refresh token revocation
-   * ```ts
-   * const result = await client.revoke(refreshToken, {
-   *   tokenTypeHint: "refresh_token"
-   * })
-   *
-   * if (result.success) {
-   *   // Token revoked successfully, user is logged out
-   *   clearStoredTokens()
-   *   redirectToHome()
-   * } else {
-   *   // Revocation failed, but still clear tokens on client
-   *   clearStoredTokens()
-   * }
-   * ```
-   */
+       * Revoke a token (access or refresh token).
+       *
+       * Once revoked, the token cannot be used to access resources or refresh.
+       * Useful for implementing logout functionality.
+       *
+       * @param token - The token to revoke
+       * @param opts - Additional revocation options
+       * @returns Empty result on success
+       *
+       * @example Logout with refresh token revocation
+       * ```ts
+       * const result = await client.revoke(refreshToken, {
+       *   tokenTypeHint: "refresh_token"
+       * })
+       *
+       * if (result.success) {
+       *   // Token revoked successfully, user is logged out
+       *   clearStoredTokens()
+       *   redirectToHome()
+       * } else {
+       *   // Revocation failed, but still clear tokens on client
+       *   clearStoredTokens()
+       * }
+       * ```
+       */
   revoke(token: string, opts?: RevokeOptions): Promise<Result<void>>;
 }
 /**