@authup/kit

Context-free helpers shared across Authup: URL pattern matching, ids, names and serialization.
The utilities the rest of the Authup monorepo builds on, with no Authup domain knowledge in them.

Installation · Usage · API · Documentation

Where it fits

@authup/kit sits at the bottom of the Authup dependency graph: @authup/core-kit, @authup/access, the HTTP client, the server packages and the consoles all import it. You get it transitively with any of them. Install it directly only when your own code wants the same redirect-pattern matching or name generation Authup uses, for example to check a redirect URI against a client's registered patterns before sending a user to Authup.

Installation

npm install @authup/kit

ESM only. Node.js >=26.0.0; the helpers use Web APIs only (URL, atob, btoa), so they also run in a browser.

Usage

Match redirect URIs against patterns

import { isSafeRedirectURLScheme, isSimpleMatch, isSimpleURLMatch } from '@authup/kit';

isSimpleURLMatch('https://app.example.com/callback', 'https://*.example.com/**'); // true
isSimpleURLMatch('https://evil.test?.example.com/cb', 'https://*.example.com/**'); // false
isSimpleMatch('users/42', ['users/*', 'roles/*']); // true

isSafeRedirectURLScheme('myapp://cb'); // true
isSafeRedirectURLScheme('javascript:alert(1)'); // false

• * matches a run of characters (the empty run included) that does not cross a /; ** matches the rest of the value. Once the value is exhausted, a separator in front of a wildcard is optional, so https://example.com matches https://example.com/**.
• isSimpleMatch compares case sensitively and knows one boundary, /. Use isSimpleURLMatch for any trust decision over a URL: it canonicalizes both the value and the pattern (host case, default port, userinfo, dot segments) first, so a wildcard in the host cannot escape into a query or fragment.
• A value that does not parse as a URL never matches. A custom scheme (myapp://cb) is compared verbatim.
• isSafeRedirectURLScheme refuses javascript:, data:, vbscript:, blob:, filesystem:, file:, about: and anything that does not parse.

Generate names, secrets and ids

import { createNanoID, generateName, generateSecret, isUUID } from '@authup/kit';

generateName(); // e.g. 'brave-otter-1a2b3c'
generateName('seed'); // the same name for the same seed
generateSecret(); // 32 characters, never seeded
createNanoID(); // 21 characters of [0-9a-z]
createNanoID(10);
isUUID('7c9e6679-7425-40de-944b-e07fc1f099d6'); // true

• generateName always returns a slug ([a-z0-9-], at most 128 characters). Pass a hydration-stable seed such as Vue's useId() to get the same name on the server and client render.
• generateSecret takes no seed on purpose: a secret must not derive from a predictable value. Generate it client-side only.

Serialize values for storage

import { deserialize, serialize } from '@authup/kit';

serialize('admin'); // '"admin"'
serialize(false); // 'false'
deserialize<boolean>('false'); // false
deserialize<string>('admin'); // 'admin'

serialize JSON-quotes strings, writes booleans, numbers, null and undefined bare, and turns a RegExp or bigint into its string form. deserialize is destr, so it reads both the quoted and a bare legacy string.

Build URLs under a sub-path

import { buildURL, getURLBasePath } from '@authup/kit';

buildURL('https://acme.tld/api', 'authorize').href; // 'https://acme.tld/api/authorize'
getURLBasePath('https://acme.tld/auth/'); // '/auth'
getURLBasePath('https://acme.tld'); // ''

new URL('authorize', 'https://acme.tld/api') drops /api; buildURL keeps it. An absent or invalid base throws, like new URL.

API

License

Made with 💚

Published under the Apache 2.0 License.