@fluixi/oauth2 1.0.0-alpha.1

package/dist/presets.d.ts

@@ -0,0 +1,140 @@
+/**
+ * Providers, as configuration rather than prose.
+ *
+ * Nothing here is required. A provider is `issuer` plus discovery, and that is the whole
+ * contract: `presets.oidc({ issuer })` is the agnostic path and covers anything publishing a
+ * discovery document, `presets.oauth2({ endpoints })` covers a plain OAuth2 server that
+ * publishes none. The named presets exist because each of the five cost a round trip to find
+ * out, and a fact learned from a live tenant belongs in code rather than in a handoff nobody
+ * reads at the right moment.
+ *
+ * What a preset does not do is decide anything an app owns. No client id, no redirect URI, no
+ * secret. It contributes the parts that follow from *which provider this is*: how the issuer
+ * is spelled, where roles live, whether an access token carries an `aud`, and what the
+ * provider will refuse outright.
+ *
+ * Every preset is a plain object. Read one, disagree with it, spread it and override the
+ * field. That is the intended use as much as taking it whole.
+ */
+import type { TokenClaims } from './verify.js';
+import type { Endpoints } from './types.js';
+/** Verifier options that follow from the provider, given the client this app is. */
+export interface VerifierShape {
+    issuer: string | string[];
+    /** `false` for a provider that puts no `aud` on an access token. */
+    audience: string | string[] | false;
+    /** Set when `audience` is false, so the check moves rather than disappearing. */
+    authorizedParty?: string | string[];
+}
+/** What a provider contributes to a client config, and what it cannot do. */
+export interface ProviderPreset {
+    /** A name for messages and logs. */
+    label: string;
+    /** Spread into `createBrowserClient` or `oauthRoutes`. */
+    client: {
+        issuer?: string;
+        endpoints?: Endpoints;
+        scopes?: string[];
+        dpop?: boolean;
+        extraParams?: Record<string, string>;
+        tokenAuthMethod?: 'client_secret_basic' | 'client_secret_post' | 'private_key_jwt' | 'none';
+    };
+    /** Where this provider puts roles, for `createApiGuard`. */
+    roles: (claims: TokenClaims) => string[];
+    /** Verifier options, given the client id this app authenticates as. */
+    verifier: (clientId: string) => VerifierShape;
+    /**
+     * What this provider will refuse, learned live rather than from documentation.
+     *
+     * Worth reading before debugging: each line here was a failure that looked like a bug in
+     * this package.
+     */
+    constraints: string[];
+}
+export declare const presets: {
+    /**
+     * Any OIDC provider publishing a discovery document.
+     *
+     * The agnostic path, and the one to reach for first. A provider not listed below almost
+     * certainly works through this.
+     */
+    oidc(options: {
+        issuer: string;
+        scopes?: string[];
+        /** `false` for a provider that puts no `aud` on an access token. */
+        audience?: string | false;
+        roles?: (claims: TokenClaims) => string[];
+    }): ProviderPreset;
+    /**
+     * A plain OAuth2 server with no discovery document.
+     *
+     * Every endpoint is given, because there is nothing to ask. Token verification needs an
+     * issuer regardless, since a verifier will not accept a token without one.
+     */
+    oauth2(options: {
+        endpoints: Endpoints;
+        issuer: string;
+        scopes?: string[];
+        audience?: string | false;
+        roles?: (claims: TokenClaims) => string[];
+    }): ProviderPreset;
+    /** Keycloak. A realm is its own issuer. */
+    keycloak(options: {
+        baseUrl: string;
+        realm: string;
+        scopes?: string[];
+    }): ProviderPreset;
+    /**
+     * Auth0.
+     *
+     * `audience` is the field that decides what kind of token comes back. Without it Auth0
+     * issues an opaque token for its own userinfo endpoint and the JWT checks have nothing to
+     * work with.
+     */
+    auth0(options: {
+        domain: string;
+        /** An API identifier. Required for a JWT access token, and for refresh tokens. */
+        audience?: string;
+        scopes?: string[];
+        /** The namespaced claim an action adds. Auth0 has no built-in roles claim. */
+        rolesClaim?: string;
+    }): ProviderPreset;
+    /**
+     * Okta.
+     *
+     * Two authorization servers that are not interchangeable: a custom one per application,
+     * and the org itself for Okta's own management API.
+     */
+    okta(options: {
+        domain: string;
+        /** The custom server, default `default`. Pass `null` for the org server. */
+        authorizationServer?: string | null;
+        scopes?: string[];
+        /** Okta turns DPoP on for new applications. Default true, because that is the default there. */
+        dpop?: boolean;
+    }): ProviderPreset;
+    /**
+     * Google.
+     *
+     * Refuses a public client outright, so server mode is the only option: the token endpoint
+     * checks for a client secret before it looks at PKCE.
+     */
+    google(options?: {
+        scopes?: string[];
+        hostedDomain?: string;
+    }): ProviderPreset;
+    /**
+     * Dex.
+     *
+     * Sends no CORS headers, on discovery or the token endpoint, so a browser cannot talk to it
+     * at all. Server mode only, and giving endpoints explicitly does not help: the token request
+     * is blocked too.
+     */
+    dex(options: {
+        baseUrl: string;
+        scopes?: string[];
+    }): ProviderPreset;
+};
+/** The preset names, for an app offering a choice. */
+export type PresetName = keyof typeof presets;
+//# sourceMappingURL=presets.d.ts.map

package/dist/presets.d.ts.map

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

package/dist/presets.js

@@ -0,0 +1,182 @@
+import { rolesFrom } from './roles.js';
+/** Trailing slashes matter to an issuer comparison, so they are normalised once. */
+const trim = (url) => url.replace(/\/+$/, '');
+export const presets = {
+    /**
+     * Any OIDC provider publishing a discovery document.
+     *
+     * The agnostic path, and the one to reach for first. A provider not listed below almost
+     * certainly works through this.
+     */
+    oidc(options) {
+        return {
+            label: options.issuer,
+            client: { issuer: trim(options.issuer), scopes: options.scopes },
+            roles: options.roles ?? rolesFrom.scope,
+            verifier: (clientId) => ({
+                issuer: trim(options.issuer),
+                audience: options.audience ?? clientId,
+                ...(options.audience === false ? { authorizedParty: clientId } : {}),
+            }),
+            constraints: [],
+        };
+    },
+    /**
+     * A plain OAuth2 server with no discovery document.
+     *
+     * Every endpoint is given, because there is nothing to ask. Token verification needs an
+     * issuer regardless, since a verifier will not accept a token without one.
+     */
+    oauth2(options) {
+        return {
+            label: options.issuer,
+            client: { endpoints: options.endpoints, scopes: options.scopes },
+            roles: options.roles ?? rolesFrom.scope,
+            verifier: (clientId) => ({
+                issuer: trim(options.issuer),
+                audience: options.audience ?? clientId,
+                ...(options.audience === false ? { authorizedParty: clientId } : {}),
+            }),
+            constraints: ['Publishes no discovery document, so every endpoint is configured by hand.'],
+        };
+    },
+    /** Keycloak. A realm is its own issuer. */
+    keycloak(options) {
+        const issuer = `${trim(options.baseUrl)}/realms/${options.realm}`;
+        return {
+            label: 'Keycloak',
+            client: {
+                issuer,
+                scopes: options.scopes ?? ['openid', 'profile', 'email'],
+            },
+            roles: rolesFrom.keycloakRealm,
+            // No `aud` on an access token until an audience mapper is configured, and the client is
+            // named in `azp` instead. So the check moves to `authorizedParty` rather than being
+            // dropped: `audience: false` alone would accept a token minted for any client of the
+            // realm, which is the check being skipped.
+            verifier: (clientId) => ({ issuer, audience: false, authorizedParty: clientId }),
+            constraints: [
+                'Puts no `aud` on an access token until a dedicated audience mapper is configured. Configure one and switch the verifier to `audience: clientId`.',
+                'Revokes the whole session when an authorization code is replayed, so a replay test has to run last.',
+            ],
+        };
+    },
+    /**
+     * Auth0.
+     *
+     * `audience` is the field that decides what kind of token comes back. Without it Auth0
+     * issues an opaque token for its own userinfo endpoint and the JWT checks have nothing to
+     * work with.
+     */
+    auth0(options) {
+        const issuer = `https://${options.domain.replace(/^https?:\/\//, '').replace(/\/+$/, '')}/`;
+        return {
+            label: 'Auth0',
+            client: {
+                issuer,
+                scopes: options.scopes ?? ['openid', 'profile', 'email', 'offline_access'],
+                ...(options.audience ? { extraParams: { audience: options.audience } } : {}),
+            },
+            roles: options.rolesClaim ? rolesFrom.namespaced(options.rolesClaim) : rolesFrom.scope,
+            verifier: (clientId) => ({
+                issuer,
+                // The API identifier is the audience of an access token. Without one the token is
+                // opaque and there is nothing for a verifier to check.
+                audience: options.audience ?? false,
+                ...(options.audience ? {} : { authorizedParty: clientId }),
+            }),
+            constraints: [
+                'Issues an opaque access token unless `audience` names an API, so token verification needs it.',
+                'A refresh token needs three things together: `offline_access` in the scopes, an audience whose API has Allow Offline Access on, and Refresh Token Rotation enabled on the application. Any one missing and the scope is ignored silently.',
+                'Has no roles claim of its own. An action must add a namespaced one, and Auth0 drops a custom claim that is not a URI.',
+                'The issuer carries a trailing slash. A verifier pinned without it rejects every token.',
+            ],
+        };
+    },
+    /**
+     * Okta.
+     *
+     * Two authorization servers that are not interchangeable: a custom one per application,
+     * and the org itself for Okta's own management API.
+     */
+    okta(options) {
+        const host = `https://${options.domain.replace(/^https?:\/\//, '').replace(/\/+$/, '')}`;
+        const server = options.authorizationServer === undefined ? 'default' : options.authorizationServer;
+        const issuer = server === null ? host : `${host}/oauth2/${server}`;
+        return {
+            label: 'Okta',
+            client: {
+                issuer,
+                scopes: options.scopes ?? ['openid', 'profile', 'email', 'offline_access'],
+                dpop: options.dpop ?? true,
+            },
+            roles: rolesFrom.groups,
+            verifier: (clientId) => ({
+                issuer,
+                // An access token from a custom server is minted for that server's audience, named in
+                // the console and `api://default` by default. It does not carry the client id.
+                audience: false,
+                authorizedParty: clientId,
+            }),
+            constraints: [
+                'Two authorization servers: /oauth2/<name> for an application, the bare domain for the management API. They are not interchangeable.',
+                'Turns DPoP on by default for a new application, and an integrator org will not let you untick it.',
+                'Binds the refresh token to the DPoP key as well as the access token, so a refresh must be proved with the key that obtained it.',
+                'A public SPA cannot introspect at all. An API Services client with `private_key_jwt` has to ask instead.',
+                'Client credentials against the org server must use `private_key_jwt`, whatever the application is set to.',
+            ],
+        };
+    },
+    /**
+     * Google.
+     *
+     * Refuses a public client outright, so server mode is the only option: the token endpoint
+     * checks for a client secret before it looks at PKCE.
+     */
+    google(options = {}) {
+        return {
+            label: 'Google',
+            client: {
+                issuer: 'https://accounts.google.com',
+                scopes: options.scopes ?? ['openid', 'profile', 'email'],
+                ...(options.hostedDomain ? { extraParams: { hd: options.hostedDomain } } : {}),
+            },
+            roles: rolesFrom.scope,
+            verifier: (clientId) => ({
+                // Names itself two ways, and a service pinned to one rejects tokens carrying the
+                // other. Discovery uses the first.
+                issuer: ['https://accounts.google.com', 'accounts.google.com'],
+                audience: clientId,
+            }),
+            constraints: [
+                'Refuses a public client: the token endpoint reports `client_secret is missing` before checking PKCE, so browser mode cannot work.',
+                'Publishes its issuer both with and without a scheme, so a verifier needs both spellings.',
+                'Issues a refresh token only on the first consent unless `prompt=consent` and `access_type=offline` are sent.',
+            ],
+        };
+    },
+    /**
+     * Dex.
+     *
+     * Sends no CORS headers, on discovery or the token endpoint, so a browser cannot talk to it
+     * at all. Server mode only, and giving endpoints explicitly does not help: the token request
+     * is blocked too.
+     */
+    dex(options) {
+        const issuer = trim(options.baseUrl);
+        return {
+            label: 'Dex',
+            client: {
+                issuer,
+                scopes: options.scopes ?? ['openid', 'profile', 'email', 'offline_access'],
+            },
+            roles: rolesFrom.groups,
+            verifier: (clientId) => ({ issuer, audience: clientId }),
+            constraints: [
+                'Sends no CORS headers on discovery or the token endpoint, so browser mode cannot work. Naming the endpoints explicitly only moves the failure to the token request.',
+                'Has no admin interface. Users are static entries in its config file, and a password is a bcrypt hash.',
+                'Publishes no revocation endpoint.',
+            ],
+        };
+    },
+};

package/dist/presets.mjs

@@ -0,0 +1,217 @@
+// src/roles.ts
+var rolesFrom = {
+  /** Keycloak, realm roles. Where it puts them unless a client mapper is configured. */
+  keycloakRealm: (claims) => {
+    const realm = claims.realm_access;
+    return realm?.roles ?? [];
+  },
+  /** Keycloak, roles scoped to one client rather than the realm. */
+  keycloakClient: (clientId) => (claims) => {
+    const all = claims.resource_access;
+    return all?.[clientId]?.roles ?? [];
+  },
+  /** Okta, and anything else using a groups claim. Needs a groups claim on the token. */
+  groups: (claims) => Array.isArray(claims.groups) ? claims.groups : [],
+  /** Cognito, which namespaces the claim. */
+  cognito: (claims) => {
+    const groups = claims["cognito:groups"];
+    return Array.isArray(groups) ? groups : [];
+  },
+  /**
+   * Auth0, which requires a namespaced custom claim added by an action.
+   *
+   * `rolesFrom.namespaced('https://adafri.com/roles')`. Auth0 silently drops a custom claim
+   * that is not a URI, so an empty list here usually means the namespace, not the action.
+   */
+  namespaced: (claim) => (claims) => {
+    const value = claims[claim];
+    return Array.isArray(value) ? value : [];
+  },
+  /** The `scope` claim read as a role list, for a provider issuing no roles at all. */
+  scope: (claims) => typeof claims.scope === "string" ? claims.scope.split(" ") : []
+};
+
+// src/presets.ts
+var trim = (url) => url.replace(/\/+$/, "");
+var presets = {
+  /**
+   * Any OIDC provider publishing a discovery document.
+   *
+   * The agnostic path, and the one to reach for first. A provider not listed below almost
+   * certainly works through this.
+   */
+  oidc(options) {
+    return {
+      label: options.issuer,
+      client: { issuer: trim(options.issuer), scopes: options.scopes },
+      roles: options.roles ?? rolesFrom.scope,
+      verifier: (clientId) => ({
+        issuer: trim(options.issuer),
+        audience: options.audience ?? clientId,
+        ...options.audience === false ? { authorizedParty: clientId } : {}
+      }),
+      constraints: []
+    };
+  },
+  /**
+   * A plain OAuth2 server with no discovery document.
+   *
+   * Every endpoint is given, because there is nothing to ask. Token verification needs an
+   * issuer regardless, since a verifier will not accept a token without one.
+   */
+  oauth2(options) {
+    return {
+      label: options.issuer,
+      client: { endpoints: options.endpoints, scopes: options.scopes },
+      roles: options.roles ?? rolesFrom.scope,
+      verifier: (clientId) => ({
+        issuer: trim(options.issuer),
+        audience: options.audience ?? clientId,
+        ...options.audience === false ? { authorizedParty: clientId } : {}
+      }),
+      constraints: ["Publishes no discovery document, so every endpoint is configured by hand."]
+    };
+  },
+  /** Keycloak. A realm is its own issuer. */
+  keycloak(options) {
+    const issuer = `${trim(options.baseUrl)}/realms/${options.realm}`;
+    return {
+      label: "Keycloak",
+      client: {
+        issuer,
+        scopes: options.scopes ?? ["openid", "profile", "email"]
+      },
+      roles: rolesFrom.keycloakRealm,
+      // No `aud` on an access token until an audience mapper is configured, and the client is
+      // named in `azp` instead. So the check moves to `authorizedParty` rather than being
+      // dropped: `audience: false` alone would accept a token minted for any client of the
+      // realm, which is the check being skipped.
+      verifier: (clientId) => ({ issuer, audience: false, authorizedParty: clientId }),
+      constraints: [
+        "Puts no `aud` on an access token until a dedicated audience mapper is configured. Configure one and switch the verifier to `audience: clientId`.",
+        "Revokes the whole session when an authorization code is replayed, so a replay test has to run last."
+      ]
+    };
+  },
+  /**
+   * Auth0.
+   *
+   * `audience` is the field that decides what kind of token comes back. Without it Auth0
+   * issues an opaque token for its own userinfo endpoint and the JWT checks have nothing to
+   * work with.
+   */
+  auth0(options) {
+    const issuer = `https://${options.domain.replace(/^https?:\/\//, "").replace(/\/+$/, "")}/`;
+    return {
+      label: "Auth0",
+      client: {
+        issuer,
+        scopes: options.scopes ?? ["openid", "profile", "email", "offline_access"],
+        ...options.audience ? { extraParams: { audience: options.audience } } : {}
+      },
+      roles: options.rolesClaim ? rolesFrom.namespaced(options.rolesClaim) : rolesFrom.scope,
+      verifier: (clientId) => ({
+        issuer,
+        // The API identifier is the audience of an access token. Without one the token is
+        // opaque and there is nothing for a verifier to check.
+        audience: options.audience ?? false,
+        ...options.audience ? {} : { authorizedParty: clientId }
+      }),
+      constraints: [
+        "Issues an opaque access token unless `audience` names an API, so token verification needs it.",
+        "A refresh token needs three things together: `offline_access` in the scopes, an audience whose API has Allow Offline Access on, and Refresh Token Rotation enabled on the application. Any one missing and the scope is ignored silently.",
+        "Has no roles claim of its own. An action must add a namespaced one, and Auth0 drops a custom claim that is not a URI.",
+        "The issuer carries a trailing slash. A verifier pinned without it rejects every token."
+      ]
+    };
+  },
+  /**
+   * Okta.
+   *
+   * Two authorization servers that are not interchangeable: a custom one per application,
+   * and the org itself for Okta's own management API.
+   */
+  okta(options) {
+    const host = `https://${options.domain.replace(/^https?:\/\//, "").replace(/\/+$/, "")}`;
+    const server = options.authorizationServer === void 0 ? "default" : options.authorizationServer;
+    const issuer = server === null ? host : `${host}/oauth2/${server}`;
+    return {
+      label: "Okta",
+      client: {
+        issuer,
+        scopes: options.scopes ?? ["openid", "profile", "email", "offline_access"],
+        dpop: options.dpop ?? true
+      },
+      roles: rolesFrom.groups,
+      verifier: (clientId) => ({
+        issuer,
+        // An access token from a custom server is minted for that server's audience, named in
+        // the console and `api://default` by default. It does not carry the client id.
+        audience: false,
+        authorizedParty: clientId
+      }),
+      constraints: [
+        "Two authorization servers: /oauth2/<name> for an application, the bare domain for the management API. They are not interchangeable.",
+        "Turns DPoP on by default for a new application, and an integrator org will not let you untick it.",
+        "Binds the refresh token to the DPoP key as well as the access token, so a refresh must be proved with the key that obtained it.",
+        "A public SPA cannot introspect at all. An API Services client with `private_key_jwt` has to ask instead.",
+        "Client credentials against the org server must use `private_key_jwt`, whatever the application is set to."
+      ]
+    };
+  },
+  /**
+   * Google.
+   *
+   * Refuses a public client outright, so server mode is the only option: the token endpoint
+   * checks for a client secret before it looks at PKCE.
+   */
+  google(options = {}) {
+    return {
+      label: "Google",
+      client: {
+        issuer: "https://accounts.google.com",
+        scopes: options.scopes ?? ["openid", "profile", "email"],
+        ...options.hostedDomain ? { extraParams: { hd: options.hostedDomain } } : {}
+      },
+      roles: rolesFrom.scope,
+      verifier: (clientId) => ({
+        // Names itself two ways, and a service pinned to one rejects tokens carrying the
+        // other. Discovery uses the first.
+        issuer: ["https://accounts.google.com", "accounts.google.com"],
+        audience: clientId
+      }),
+      constraints: [
+        "Refuses a public client: the token endpoint reports `client_secret is missing` before checking PKCE, so browser mode cannot work.",
+        "Publishes its issuer both with and without a scheme, so a verifier needs both spellings.",
+        "Issues a refresh token only on the first consent unless `prompt=consent` and `access_type=offline` are sent."
+      ]
+    };
+  },
+  /**
+   * Dex.
+   *
+   * Sends no CORS headers, on discovery or the token endpoint, so a browser cannot talk to it
+   * at all. Server mode only, and giving endpoints explicitly does not help: the token request
+   * is blocked too.
+   */
+  dex(options) {
+    const issuer = trim(options.baseUrl);
+    return {
+      label: "Dex",
+      client: {
+        issuer,
+        scopes: options.scopes ?? ["openid", "profile", "email", "offline_access"]
+      },
+      roles: rolesFrom.groups,
+      verifier: (clientId) => ({ issuer, audience: clientId }),
+      constraints: [
+        "Sends no CORS headers on discovery or the token endpoint, so browser mode cannot work. Naming the endpoints explicitly only moves the failure to the token request.",
+        "Has no admin interface. Users are static entries in its config file, and a password is a bcrypt hash.",
+        "Publishes no revocation endpoint."
+      ]
+    };
+  }
+};
+export {
+  presets
+};

package/dist/return-to.cjs

@@ -0,0 +1,46 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/return-to.ts
+var return_to_exports = {};
+__export(return_to_exports, {
+  safeReturnTo: () => safeReturnTo
+});
+module.exports = __toCommonJS(return_to_exports);
+function safeReturnTo(candidate, options = {}) {
+  const fallback = options.fallback ?? "/";
+  if (!candidate || typeof candidate !== "string") return fallback;
+  const value = candidate.trim();
+  if (!value) return fallback;
+  if (/[\u0000-\u001f\u007f]/.test(value)) return fallback;
+  if (/^[/\\]{2}/.test(value)) return fallback;
+  if (value.startsWith("/")) return value;
+  const here = options.origin ?? (typeof location === "undefined" ? void 0 : location.origin);
+  const allowed = [here, ...options.allowedOrigins ?? []].filter(Boolean);
+  if (!allowed.length) return fallback;
+  let url;
+  try {
+    url = new URL(value);
+  } catch {
+    return fallback;
+  }
+  if (!allowed.includes(url.origin)) return fallback;
+  if (url.protocol !== "http:" && url.protocol !== "https:") return fallback;
+  return url.toString();
+}

package/dist/return-to.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Where a completed login is allowed to land.
+ *
+ * A login flow carries a destination so a visitor resumes where they were interrupted,
+ * and that destination arrives from outside: a query parameter, a caller's argument, a
+ * value read back out of storage. Redirecting to it unchecked is an open redirect, and a
+ * login is the worst place to have one. The visitor has just authenticated, so the page
+ * they land on is trusted by them and reached with a live session.
+ *
+ * Sealing the value does not help. A signed cookie cannot be tampered with, and an
+ * attacker putting `?returnTo=https://evil.example/` on a link has no need to tamper: the
+ * application seals the attacker's value itself and honours it afterwards.
+ *
+ * So the rule is what the value is allowed to be, rather than where it came from. A path
+ * on this origin, and nothing else.
+ */
+/** What a destination has to look like to be used. */
+export interface ReturnToOptions {
+    /**
+     * Where to go when the destination is missing or refused. Default `/`.
+     *
+     * A refusal falls back rather than failing: someone who followed a poisoned link should
+     * still end up signed in, on a page of this application's choosing.
+     */
+    fallback?: string;
+    /**
+     * Origins allowed in addition to this one, for an application that really does span
+     * several. Each must be an exact origin, `https://app.example.com`, and is compared as
+     * one rather than by prefix, so `https://app.example.com.evil.test` cannot pass.
+     */
+    allowedOrigins?: string[];
+    /** This origin, when it cannot be read from `location`. Required on a server. */
+    origin?: string;
+}
+/**
+ * The destination to use, which is `candidate` when it is safe and the fallback when not.
+ *
+ * Refused, with reasons:
+ *
+ * - an absolute URL on another origin, which is the open redirect itself
+ * - `//host`, which a browser reads as protocol-relative and therefore another origin
+ * - `\\host`, which some browsers normalise to the same thing
+ * - a scheme of any kind, so `javascript:` and `data:` cannot be reached
+ * - a control character, which can be used to smuggle a newline past a naive check
+ * - anything that is not a path, since a bare `dashboard` resolves differently depending
+ *   on where it is used
+ */
+export declare function safeReturnTo(candidate: string | null | undefined, options?: ReturnToOptions): string;
+//# sourceMappingURL=return-to.d.ts.map

package/dist/return-to.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"return-to.d.ts","sourceRoot":"","sources":["../src/return-to.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,sDAAsD;AACtD,MAAM,WAAW,eAAe;IAC9B;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;;OAIG;IACH,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;IAC1B,iFAAiF;IACjF,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,YAAY,CAC1B,SAAS,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,EACpC,OAAO,GAAE,eAAoB,GAC5B,MAAM,CA0CR"}