offrouter-core 0.2.0 → 0.2.2

package/dist/auth/credential-chain.js

@@ -0,0 +1,150 @@
+/**
+ * Credential-chain resolution for OffRouter.
+ *
+ * Tries each source in order: env -> config -> keychain -> (oauth, opt-in).
+ * Never logs secret values. Uses Redacted<T> wrapper for safe output.
+ * Never scrapes other CLI credential stores.
+ */
+import { accountStorageKey, getOAuthTokens, isOAuthTokenExpired, } from "./keychain.js";
+// ---------------------------------------------------------------------------
+// Redacted wrapper
+// ---------------------------------------------------------------------------
+/**
+ * Wrapper that hides secret material from JSON serialization and string
+ * conversion. The raw value is accessible via `.rawValue` for use in
+ * Authorization headers, never for logging.
+ */
+export class Redacted {
+    #value;
+    constructor(value) {
+        this.#value = value;
+    }
+    /** Access the raw secret value. Use only for provider API calls. */
+    get rawValue() {
+        return this.#value;
+    }
+    /** Returns a constant redacted string for JSON serialization. */
+    toJSON() {
+        return "[REDACTED]";
+    }
+    /** Returns a constant redacted string for debugging. */
+    toString() {
+        return "[REDACTED]";
+    }
+}
+/**
+ * Resolve a credential by trying each source in order.
+ * Returns the first non-empty value, or null if all sources are empty.
+ */
+export async function resolveCredential(sources, opts) {
+    for (const source of sources) {
+        const value = await trySource(source, opts);
+        if (value !== null) {
+            return { value: new Redacted(value), source: source.type };
+        }
+    }
+    return null;
+}
+/**
+ * Try a single credential source.
+ * Returns the raw secret string or null if not found.
+ */
+async function trySource(source, opts) {
+    switch (source.type) {
+        case "env": {
+            return tryEnv(source.name);
+        }
+        case "config": {
+            return tryConfig(source.key, opts.config);
+        }
+        case "keychain": {
+            return tryKeychain(source.providerId, opts.store, source.accountId);
+        }
+        case "oauth": {
+            // Resolve stored OAuth tokens. This does NOT trigger a login flow;
+            // it resolves tokens already obtained via the `login` command.
+            // If the token is expired and a refresher is wired, try refreshing.
+            return tryOAuth(source.provider, opts.store, opts.refreshOAuthToken);
+        }
+    }
+}
+/**
+ * Read a value from environment variables.
+ */
+function tryEnv(name) {
+    const value = process.env[name];
+    if (typeof value === "string" && value.trim().length > 0) {
+        return value.trim();
+    }
+    return null;
+}
+/**
+ * Read a value from trusted config using dot-notation path.
+ * Only reads from config if provided (trusted source).
+ * Path format: "providers.{providerId}.apiKey"
+ */
+function tryConfig(key, config) {
+    if (!config) {
+        return null;
+    }
+    const parts = key.split(".");
+    let current = config;
+    for (const part of parts) {
+        if (typeof current !== "object" || current === null) {
+            return null;
+        }
+        const obj = current;
+        if (!(part in obj)) {
+            return null;
+        }
+        current = obj[part];
+    }
+    if (typeof current === "string" && current.trim().length > 0) {
+        return current.trim();
+    }
+    return null;
+}
+/**
+ * Read a value from the secret store (keychain-backed).
+ */
+async function tryKeychain(providerId, store, accountId) {
+    try {
+        const key = accountStorageKey(providerId, accountId);
+        const value = await store.get(key);
+        if (typeof value === "string" && value.trim().length > 0) {
+            return value.trim();
+        }
+    }
+    catch {
+        // KeychainUnavailableError or other errors: treat as missing.
+    }
+    return null;
+}
+/**
+ * Resolve a credential from stored OAuth tokens (no new login flow).
+ * Returns the access token if valid, triggers refresh if expired + wired,
+ * or returns null if no tokens exist or refresh fails.
+ */
+async function tryOAuth(providerId, store, refresh) {
+    try {
+        const tokens = await getOAuthTokens(providerId, store);
+        if (!tokens)
+            return null;
+        if (!isOAuthTokenExpired(tokens)) {
+            return tokens.accessToken;
+        }
+        // Expired: try refresh if a refresher is wired.
+        if (!refresh)
+            return null;
+        try {
+            return await refresh(providerId);
+        }
+        catch {
+            return null;
+        }
+    }
+    catch {
+        return null;
+    }
+}
+//# sourceMappingURL=credential-chain.js.map

package/dist/auth/credential-chain.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"credential-chain.js","sourceRoot":"","sources":["../../src/auth/credential-chain.ts"],"names":[],"mappings":"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"}

package/dist/auth/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Auth module barrel export for OffRouter.
+ */
+export { Redacted, resolveCredential, } from "./credential-chain.js";
+export type { CredentialResult, CredentialSource, ResolveCredentialOptions, } from "./credential-chain.js";
+export { deleteOAuthTokens, getOAuthTokens, getProviderToken, isOAuthTokenExpired, setOAuthTokens, setProviderToken, } from "./keychain.js";
+export type { OAuthStoredTokens } from "./keychain.js";
+export { defaultCallbackPort, exchangeCodeForTokens, generateCodeChallenge, generateCodeVerifier, isOAuthProvider, PKCE_CONFIGS, refreshTokens, resolveClientId, runOAuthLogin, startOAuthFlow, } from "./oauth-pkce.js";
+export type { OAuthFlowResult, OAuthFlowState, OAuthProviderConfig, OAuthStartOptions, OAuthTokenOptions, OAuthTokenResponse, RunOAuthLoginOptions, RunOAuthLoginResult, } from "./oauth-pkce.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/auth/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/auth/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,OAAO,EACL,QAAQ,EACR,iBAAiB,GAClB,MAAM,uBAAuB,CAAC;AAC/B,YAAY,EACV,gBAAgB,EAChB,gBAAgB,EAChB,wBAAwB,GACzB,MAAM,uBAAuB,CAAC;AAE/B,OAAO,EACL,iBAAiB,EACjB,cAAc,EACd,gBAAgB,EAChB,mBAAmB,EACnB,cAAc,EACd,gBAAgB,GACjB,MAAM,eAAe,CAAC;AACvB,YAAY,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AAEvD,OAAO,EACL,mBAAmB,EACnB,qBAAqB,EACrB,qBAAqB,EACrB,oBAAoB,EACpB,eAAe,EACf,YAAY,EACZ,aAAa,EACb,eAAe,EACf,aAAa,EACb,cAAc,GACf,MAAM,iBAAiB,CAAC;AACzB,YAAY,EACV,eAAe,EACf,cAAc,EACd,mBAAmB,EACnB,iBAAiB,EACjB,iBAAiB,EACjB,kBAAkB,EAClB,oBAAoB,EACpB,mBAAmB,GACpB,MAAM,iBAAiB,CAAC"}

package/dist/auth/index.js

@@ -0,0 +1,7 @@
+/**
+ * Auth module barrel export for OffRouter.
+ */
+export { Redacted, resolveCredential, } from "./credential-chain.js";
+export { deleteOAuthTokens, getOAuthTokens, getProviderToken, isOAuthTokenExpired, setOAuthTokens, setProviderToken, } from "./keychain.js";
+export { defaultCallbackPort, exchangeCodeForTokens, generateCodeChallenge, generateCodeVerifier, isOAuthProvider, PKCE_CONFIGS, refreshTokens, resolveClientId, runOAuthLogin, startOAuthFlow, } from "./oauth-pkce.js";
+//# sourceMappingURL=index.js.map

package/dist/auth/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/auth/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,OAAO,EACL,QAAQ,EACR,iBAAiB,GAClB,MAAM,uBAAuB,CAAC;AAO/B,OAAO,EACL,iBAAiB,EACjB,cAAc,EACd,gBAAgB,EAChB,mBAAmB,EACnB,cAAc,EACd,gBAAgB,GACjB,MAAM,eAAe,CAAC;AAGvB,OAAO,EACL,mBAAmB,EACnB,qBAAqB,EACrB,qBAAqB,EACrB,oBAAoB,EACpB,eAAe,EACf,YAAY,EACZ,aAAa,EACb,eAAe,EACf,aAAa,EACb,cAAc,GACf,MAAM,iBAAiB,CAAC"}

package/dist/auth/keychain.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Keychain-backed token helpers for OffRouter.
+ *
+ * Provides getProviderToken/setProviderToken that use the SecretStore
+ * abstraction (file or OS keychain). Never scrapes other CLI credential stores.
+ *
+ * Per-account token storage: when accountId is provided and differs from
+ * providerId, the storage key is "${providerId}:${accountId}". Otherwise the
+ * plain providerId is used for backward compatibility with existing tokens.
+ */
+import type { SecretStore } from "../secrets.js";
+import { Redacted } from "./credential-chain.js";
+/**
+ * Compute the storage key for a provider+account combination.
+ * Backward compatible: when accountId is absent or equals providerId, returns
+ * the plain providerId so existing tokens resolve.
+ */
+export declare function accountStorageKey(providerId: string, accountId?: string): string;
+/**
+ * Retrieve a provider token from the secret store.
+ * Returns undefined if no token is stored or the store is unavailable.
+ */
+export declare function getProviderToken(providerId: string, store: SecretStore, accountId?: string): Promise<Redacted<string> | undefined>;
+/**
+ * Store a provider token in the secret store.
+ * Throws if the store is unavailable (e.g., KeychainUnavailableError).
+ */
+export declare function setProviderToken(providerId: string, token: string, store: SecretStore, accountId?: string): Promise<void>;
+/**
+ * Structured OAuth token material stored under "${providerId}[:account]:oauth".
+ * accessToken is the bearer used for provider calls; refreshToken drives
+ * silent refresh; expiresAt/obtainedAt are epoch milliseconds. Stored as JSON
+ * so the whole token set moves atomically and stays separate from API keys.
+ */
+export interface OAuthStoredTokens {
+    accessToken: string;
+    refreshToken?: string;
+    expiresAt?: number;
+    scope?: string;
+    obtainedAt: number;
+}
+/** Compute the secret-store key for a provider+account OAuth token set. */
+export declare function oauthStorageKey(providerId: string, accountId?: string): string;
+/**
+ * Store structured OAuth tokens (access, optional refresh, expiry, scope).
+ */
+export declare function setOAuthTokens(providerId: string, tokens: OAuthStoredTokens, store: SecretStore, accountId?: string): Promise<void>;
+/**
+ * Retrieve structured OAuth tokens. Returns undefined if nothing is stored,
+ * the store is unavailable, or the stored payload is corrupt.
+ */
+export declare function getOAuthTokens(providerId: string, store: SecretStore, accountId?: string): Promise<OAuthStoredTokens | undefined>;
+/** Remove stored OAuth tokens for a provider+account. */
+export declare function deleteOAuthTokens(providerId: string, store: SecretStore, accountId?: string): Promise<void>;
+/**
+ * Returns true when the access token is expired or within the skew window.
+ * Tokens without an expiresAt are treated as not expired (no expiry known).
+ */
+export declare function isOAuthTokenExpired(tokens: OAuthStoredTokens, now?: number, skewMs?: number): boolean;
+//# sourceMappingURL=keychain.d.ts.map

package/dist/auth/keychain.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"keychain.d.ts","sourceRoot":"","sources":["../../src/auth/keychain.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AACjD,OAAO,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AAEjD;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,UAAU,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,MAAM,CAGhF;AAED;;;GAGG;AACH,wBAAsB,gBAAgB,CACpC,UAAU,EAAE,MAAM,EAClB,KAAK,EAAE,WAAW,EAClB,SAAS,CAAC,EAAE,MAAM,GACjB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAC,GAAG,SAAS,CAAC,CAWvC;AAED;;;GAGG;AACH,wBAAsB,gBAAgB,CACpC,UAAU,EAAE,MAAM,EAClB,KAAK,EAAE,MAAM,EACb,KAAK,EAAE,WAAW,EAClB,SAAS,CAAC,EAAE,MAAM,GACjB,OAAO,CAAC,IAAI,CAAC,CAGf;AASD;;;;;GAKG;AACH,MAAM,WAAW,iBAAiB;IAChC,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,2EAA2E;AAC3E,wBAAgB,eAAe,CAC7B,UAAU,EAAE,MAAM,EAClB,SAAS,CAAC,EAAE,MAAM,GACjB,MAAM,CAER;AAED;;GAEG;AACH,wBAAsB,cAAc,CAClC,UAAU,EAAE,MAAM,EAClB,MAAM,EAAE,iBAAiB,EACzB,KAAK,EAAE,WAAW,EAClB,SAAS,CAAC,EAAE,MAAM,GACjB,OAAO,CAAC,IAAI,CAAC,CAGf;AAED;;;GAGG;AACH,wBAAsB,cAAc,CAClC,UAAU,EAAE,MAAM,EAClB,KAAK,EAAE,WAAW,EAClB,SAAS,CAAC,EAAE,MAAM,GACjB,OAAO,CAAC,iBAAiB,GAAG,SAAS,CAAC,CA8BxC;AAED,yDAAyD;AACzD,wBAAsB,iBAAiB,CACrC,UAAU,EAAE,MAAM,EAClB,KAAK,EAAE,WAAW,EAClB,SAAS,CAAC,EAAE,MAAM,GACjB,OAAO,CAAC,IAAI,CAAC,CAOf;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,CACjC,MAAM,EAAE,iBAAiB,EACzB,GAAG,GAAE,MAAmB,EACxB,MAAM,SAAS,GACd,OAAO,CAKT"}

package/dist/auth/keychain.js

@@ -0,0 +1,104 @@
+import { Redacted } from "./credential-chain.js";
+/**
+ * Compute the storage key for a provider+account combination.
+ * Backward compatible: when accountId is absent or equals providerId, returns
+ * the plain providerId so existing tokens resolve.
+ */
+export function accountStorageKey(providerId, accountId) {
+    if (!accountId || accountId === providerId)
+        return providerId;
+    return `${providerId}:${accountId}`;
+}
+/**
+ * Retrieve a provider token from the secret store.
+ * Returns undefined if no token is stored or the store is unavailable.
+ */
+export async function getProviderToken(providerId, store, accountId) {
+    try {
+        const key = accountStorageKey(providerId, accountId);
+        const value = await store.get(key);
+        if (typeof value === "string" && value.length > 0) {
+            return new Redacted(value);
+        }
+    }
+    catch {
+        // KeychainUnavailableError or other errors: treat as missing.
+    }
+    return undefined;
+}
+/**
+ * Store a provider token in the secret store.
+ * Throws if the store is unavailable (e.g., KeychainUnavailableError).
+ */
+export async function setProviderToken(providerId, token, store, accountId) {
+    const key = accountStorageKey(providerId, accountId);
+    await store.set(key, token);
+}
+// ---------------------------------------------------------------------------
+// OAuth token storage (structured, separate from API-key tokens)
+// ---------------------------------------------------------------------------
+/** Suffix that namespaces structured OAuth token blobs in the secret store. */
+const OAUTH_SUFFIX = ":oauth";
+/** Compute the secret-store key for a provider+account OAuth token set. */
+export function oauthStorageKey(providerId, accountId) {
+    return `${accountStorageKey(providerId, accountId)}${OAUTH_SUFFIX}`;
+}
+/**
+ * Store structured OAuth tokens (access, optional refresh, expiry, scope).
+ */
+export async function setOAuthTokens(providerId, tokens, store, accountId) {
+    const key = oauthStorageKey(providerId, accountId);
+    await store.set(key, JSON.stringify(tokens));
+}
+/**
+ * Retrieve structured OAuth tokens. Returns undefined if nothing is stored,
+ * the store is unavailable, or the stored payload is corrupt.
+ */
+export async function getOAuthTokens(providerId, store, accountId) {
+    try {
+        const key = oauthStorageKey(providerId, accountId);
+        const raw = await store.get(key);
+        if (typeof raw !== "string" || raw.length === 0) {
+            return undefined;
+        }
+        const parsed = JSON.parse(raw);
+        if (typeof parsed.accessToken !== "string" ||
+            parsed.accessToken.length === 0) {
+            return undefined;
+        }
+        return {
+            accessToken: parsed.accessToken,
+            refreshToken: typeof parsed.refreshToken === "string" && parsed.refreshToken.length > 0
+                ? parsed.refreshToken
+                : undefined,
+            expiresAt: typeof parsed.expiresAt === "number" ? parsed.expiresAt : undefined,
+            scope: typeof parsed.scope === "string" ? parsed.scope : undefined,
+            obtainedAt: typeof parsed.obtainedAt === "number" ? parsed.obtainedAt : Date.now(),
+        };
+    }
+    catch {
+        // Corrupt payload or unavailable store: treat as missing.
+        return undefined;
+    }
+}
+/** Remove stored OAuth tokens for a provider+account. */
+export async function deleteOAuthTokens(providerId, store, accountId) {
+    try {
+        const key = oauthStorageKey(providerId, accountId);
+        await store.delete(key);
+    }
+    catch {
+        // Unavailable store: nothing to delete.
+    }
+}
+/**
+ * Returns true when the access token is expired or within the skew window.
+ * Tokens without an expiresAt are treated as not expired (no expiry known).
+ */
+export function isOAuthTokenExpired(tokens, now = Date.now(), skewMs = 60_000) {
+    if (typeof tokens.expiresAt !== "number") {
+        return false;
+    }
+    return now + skewMs >= tokens.expiresAt;
+}
+//# sourceMappingURL=keychain.js.map

package/dist/auth/keychain.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"keychain.js","sourceRoot":"","sources":["../../src/auth/keychain.ts"],"names":[],"mappings":"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"}

package/dist/auth/oauth-pkce.d.ts

@@ -0,0 +1,138 @@
+import type { SecretStore } from "../secrets.js";
+import { Redacted } from "./credential-chain.js";
+/**
+ * Generate a random code verifier for PKCE (RFC 7636).
+ * Length is between 43 and 128 characters.
+ */
+export declare function generateCodeVerifier(): string;
+/**
+ * Generate a S256 code challenge from a verifier (RFC 7636).
+ * Uses Web Crypto API (available in Node >= 22, Workers, browsers).
+ */
+export declare function generateCodeChallenge(verifier: string): Promise<string>;
+export interface OAuthProviderConfig {
+    authorizeUrl: string;
+    tokenUrl: string;
+    scopes: string[];
+    defaultClientId?: string;
+    clientIdEnvVar?: string;
+}
+/**
+ * OAuth PKCE configurations for supported providers.
+ * Only Anthropic and OpenAI/Codex are supported.
+ * Gemini/xAI/Z.ai are API-key only.
+ */
+export declare const PKCE_CONFIGS: Record<string, OAuthProviderConfig>;
+/**
+ * Returns true if the provider supports OAuth (opt-in).
+ */
+export declare function isOAuthProvider(providerId: string): boolean;
+/**
+ * In-memory session data associated with a PKCE nonce.
+ * Never serialised into the caller-visible state string.
+ */
+export interface OAuthSession {
+    codeVerifier: string;
+    redirectUri: string;
+    createdAt: number;
+}
+/**
+ * Retrieve and delete a session by nonce (one-shot consume).
+ * Returns null if the nonce is unknown, already consumed, or expired.
+ */
+export declare function consumeOAuthSession(nonce: string): OAuthSession | null;
+/**
+ * Cancel / discard a session without consuming it.
+ */
+export declare function cancelOAuthSession(nonce: string): void;
+export interface OAuthFlowState {
+    provider: string;
+    nonce: string;
+}
+export interface OAuthFlowResult {
+    authorizeUrl: string;
+    state: string;
+}
+export interface OAuthTokenResponse {
+    accessToken: Redacted<string>;
+    refreshToken?: Redacted<string>;
+    expiresIn?: number;
+    scope?: string;
+}
+export interface OAuthStartOptions {
+    redirectUri: string;
+    /** Override client ID (default from env or PKCE_CONFIGS). */
+    clientId?: string;
+}
+export interface OAuthTokenOptions {
+    store: SecretStore;
+    fetch?: typeof globalThis.fetch;
+}
+/**
+ * Create an OAuth state string that encodes provider metadata.
+ * Used to validate the callback matches the initiated flow.
+ */
+export declare function createOAuthState(provider: string): string;
+/**
+ * Start an OAuth PKCE flow for the given provider.
+ * Returns the authorization URL and state for redirect.
+ * Never auto-triggers; requires explicit user configuration.
+ */
+export declare function startOAuthFlow(provider: string, options: OAuthStartOptions): Promise<OAuthFlowResult>;
+/**
+ * Exchange an authorization code for tokens.
+ * Called after the user completes the OAuth flow in their browser.
+ */
+export declare function exchangeCodeForTokens(provider: string, code: string, statePayload: string, options: OAuthTokenOptions): Promise<OAuthTokenResponse>;
+/**
+ * Return the default callback port for a provider, or 0 (OS-assigned).
+ */
+export declare function defaultCallbackPort(provider: string): number;
+/**
+ * Resolve the client id for a provider from process env (or a provided env
+ * override). Returns undefined if the env var is not set.
+ */
+export declare function resolveClientId(provider: string, env?: NodeJS.ProcessEnv): string | undefined;
+export interface RunOAuthLoginOptions {
+    provider: string;
+    store: SecretStore;
+    /** Override client id (else resolved from env / PKCE_CONFIGS). */
+    clientId?: string;
+    /** Loopback port (defaults to provider default or 0). */
+    port?: number;
+    /** Wait timeout in ms (default 5 min). */
+    timeoutMs?: number;
+    /** Called with the authorize URL once built (test/display). */
+    onAuthorizeUrl?: (url: string) => void;
+    /** Best-effort browser open (non-throwing). */
+    openBrowser?: (url: string) => Promise<boolean> | boolean;
+    /** Injectable fetch (tests). */
+    fetch?: typeof globalThis.fetch;
+    /** Optional abort signal. */
+    signal?: AbortSignal;
+}
+export interface RunOAuthLoginResult {
+    provider: string;
+    redirectUri: string;
+    expiresAt?: number;
+    scope?: string;
+}
+/**
+ * Run the full OAuth PKCE login flow:
+ * 1. Start a local callback server on 127.0.0.1
+ * 2. Build the authorize URL with PKCE challenge + state
+ * 3. Notify caller (onAuthorizeUrl) and attempt browser open
+ * 4. Wait for the provider callback (code + state)
+ * 5. Exchange code for tokens
+ * 6. Store structured tokens in the secret store
+ * 7. Clean up the server
+ */
+export declare function runOAuthLogin(opts: RunOAuthLoginOptions): Promise<RunOAuthLoginResult>;
+/**
+ * Refresh an OAuth token using a refresh token.
+ * Updates the stored tokens on success.
+ */
+export declare function refreshTokens(provider: string, refreshToken: string, store: SecretStore, options?: {
+    fetch?: typeof globalThis.fetch;
+}): Promise<OAuthTokenResponse>;
+//# sourceMappingURL=oauth-pkce.d.ts.map

package/dist/auth/oauth-pkce.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"oauth-pkce.d.ts","sourceRoot":"","sources":["../../src/auth/oauth-pkce.ts"],"names":[],"mappings":"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"}