@atcute/oauth-types 0.1.0

package/lib/schemas/uri.ts

@@ -0,0 +1,100 @@
+import * as v from '@badrap/valita';
+
+import { isHostnameIP, isLocalHostname, isLoopbackHost } from './utils.js';
+
+/**
+ * valid, but potentially dangerous URL (`data:`, `file:`, `javascript:`, etc.).
+ *
+ * any value that matches this schema is safe to parse using `new URL()`.
+ */
+export const urlSchema = v.string().chain((input) => {
+	if (input.includes(':') && URL.canParse(input)) {
+		return v.ok(input);
+	}
+	return v.err(`must be a valid url`);
+});
+
+/** loopback URL (http://localhost, http://127.0.0.1, http://[::1]) */
+export const loopbackUriSchema = urlSchema.chain((input) => {
+	if (!input.startsWith('http://')) {
+		return v.err(`loopback url must use http: protocol`);
+	}
+
+	const url = new URL(input);
+	if (!isLoopbackHost(url.hostname)) {
+		return v.err(`loopback url must use localhost, 127.0.0.1, or [::1] as hostname`);
+	}
+
+	return v.ok(input);
+});
+
+/** HTTPS URL with additional restrictions */
+export const httpsUriSchema = urlSchema.chain((input) => {
+	if (!input.startsWith('https://')) {
+		return v.err(`url must use https: protocol`);
+	}
+
+	const url = new URL(input);
+
+	if (isLoopbackHost(url.hostname)) {
+		return v.err(`https url must not use a loopback host`);
+	}
+
+	if (!isHostnameIP(url.hostname)) {
+		if (!url.hostname.includes('.')) {
+			return v.err(`domain name must contain at least two segments`);
+		}
+		if (url.hostname.endsWith('.local')) {
+			return v.err(`domain name must not end with .local`);
+		}
+	}
+
+	return v.ok(input);
+});
+
+/** web URL (either loopback http or https) */
+export const webUriSchema = urlSchema.chain((input, options) => {
+	if (input.startsWith('http://')) {
+		return loopbackUriSchema.try(input, options);
+	}
+
+	if (input.startsWith('https://')) {
+		return httpsUriSchema.try(input, options);
+	}
+
+	return v.err(`url must use http: or https: protocol`);
+});
+
+/** web URL with a non-local hostname */
+export const nonLocalWebUriSchema = webUriSchema.chain((input) => {
+	const url = new URL(input);
+	if (isLocalHostname(url.hostname)) {
+		return v.err(`hostname is invalid`);
+	}
+	return v.ok(input);
+});
+
+/** private-use URI scheme (e.g., com.example.app:/callback) */
+export const privateUseUriSchema = urlSchema.chain((input) => {
+	const dotIdx = input.indexOf('.');
+	const colonIdx = input.indexOf(':');
+
+	if (dotIdx === -1 || colonIdx === -1 || dotIdx > colonIdx) {
+		return v.err(`private-use uri scheme must contain a dot in the protocol`);
+	}
+
+	const url = new URL(input);
+	const scheme = url.protocol.slice(0, -1);
+	const domain = scheme.split('.').reverse().join('.');
+
+	if (isLocalHostname(domain)) {
+		return v.err(`private-use uri scheme must not be a local hostname`);
+	}
+
+	// RFC 8252: private-use URIs must use single slash after scheme
+	if (url.href.startsWith(`${url.protocol}//`) || url.username || url.password || url.hostname || url.port) {
+		return v.err(`private-use uri must be in the form scheme:/<path>`);
+	}
+
+	return v.ok(input);
+});

package/lib/schemas/utils.ts

@@ -0,0 +1,113 @@
+/**
+ * checks if a hostname is a loopback address
+ */
+export const isLoopbackHost = (hostname: string): boolean => {
+	return hostname === 'localhost' || hostname === '127.0.0.1' || hostname === '[::1]';
+};
+
+/**
+ * checks if a hostname is an IP address (IPv4 or IPv6)
+ */
+export const isHostnameIP = (hostname: string): boolean => {
+	// IPv4
+	if (/^\d+\.\d+\.\d+\.\d+$/.test(hostname)) {
+		return true;
+	}
+	// IPv6
+	if (hostname.startsWith('[') && hostname.endsWith(']')) {
+		return true;
+	}
+	return false;
+};
+
+/**
+ * checks if a hostname is a local/reserved hostname
+ *
+ * returns true for single-segment hostnames and reserved TLDs
+ */
+export const isLocalHostname = (hostname: string): boolean => {
+	const parts = hostname.split('.');
+	if (parts.length < 2) {
+		return true;
+	}
+
+	const tld = parts.at(-1)!.toLowerCase();
+	return tld === 'test' || tld === 'local' || tld === 'localhost' || tld === 'invalid' || tld === 'example';
+};
+
+/**
+ * extracts the path from a URL without relying on URL constructor normalization
+ *
+ * this is needed because the URL constructor normalizes paths (e.g., removes `.` and `..` segments),
+ * which can be used to bypass validation checks
+ */
+export const extractUrlPath = (url: string): string => {
+	const endOfProtocol = url.startsWith('https://') ? 8 : url.startsWith('http://') ? 7 : -1;
+	if (endOfProtocol === -1) {
+		throw new TypeError(`url must use https: or http: protocol`);
+	}
+
+	const hashIdx = url.indexOf('#', endOfProtocol);
+	const questionIdx = url.indexOf('?', endOfProtocol);
+
+	const queryStrIdx = questionIdx !== -1 && (hashIdx === -1 || questionIdx < hashIdx) ? questionIdx : -1;
+
+	const pathEnd =
+		hashIdx === -1
+			? queryStrIdx === -1
+				? url.length
+				: queryStrIdx
+			: queryStrIdx === -1
+				? hashIdx
+				: Math.min(hashIdx, queryStrIdx);
+
+	const slashIdx = url.indexOf('/', endOfProtocol);
+	const pathStart = slashIdx === -1 || slashIdx > pathEnd ? pathEnd : slashIdx;
+
+	if (endOfProtocol === pathStart) {
+		throw new TypeError(`url must contain a host`);
+	}
+
+	return url.substring(pathStart, pathEnd) || '/';
+};
+
+/**
+ * checks if an item is the last occurrence in an array (for duplicate detection)
+ */
+export const isLastOccurrence = <T>(item: T, index: number, array: readonly T[]): boolean => {
+	return array.lastIndexOf(item) === index;
+};
+
+/**
+ * checks if a space-separated string contains a specific value
+ *
+ * optimized version of `input.split(' ').includes(value)`
+ */
+export const isSpaceSeparatedValue = (value: string, input: string): boolean => {
+	const inputLength = input.length;
+	const valueLength = value.length;
+
+	if (inputLength < valueLength) {
+		return false;
+	}
+
+	let idx = input.indexOf(value);
+	let idxEnd: number;
+
+	while (idx !== -1) {
+		idxEnd = idx + valueLength;
+
+		if (
+			// at beginning or preceded by space
+			(idx === 0 || input.charCodeAt(idx - 1) === 32) &&
+			// at end or followed by space
+			(idxEnd === inputLength || input.charCodeAt(idxEnd) === 32)
+		) {
+			return true;
+		}
+
+		idx = input.indexOf(value, idxEnd + 1);
+	}
+
+	return false;
+};

package/lib/scope.ts

@@ -0,0 +1,187 @@
+import type { AtprotoAudience, Nsid } from '@atcute/lexicons/syntax';
+
+/** repo record actions */
+export type RepoAction = 'create' | 'update' | 'delete';
+
+/** account attributes */
+export type AccountAttr = 'email' | 'repo' | 'status';
+
+/** account actions */
+export type AccountAction = 'read' | 'manage';
+
+/** identity attributes */
+export type IdentityAttr = 'handle' | '*';
+
+/** collection parameter - NSID or wildcard */
+export type CollectionParam = Nsid | '*';
+
+/** lexicon method parameter - NSID or wildcard */
+export type LxmParam = Nsid | '*';
+
+/** audience parameter - atproto audience or wildcard */
+export type AudParam = AtprotoAudience | '*';
+
+export interface RepoOptions {
+	/** collection NSID(s) or '*' for all */
+	collection: CollectionParam[];
+	/** allowed actions; if omitted, all operations are permitted */
+	action?: RepoAction[];
+}
+
+/**
+ * builds a repo permission scope
+ * @param options repo permission options
+ * @returns scope string like `repo?collection=app.bsky.feed.post&action=create&action=update`
+ */
+export const repo = (options: RepoOptions): string => {
+	const { collection, action = [] } = options;
+
+	const params = new URLSearchParams();
+	for (const c of collection) {
+		params.append('collection', c);
+	}
+
+	for (const a of action) {
+		params.append('action', a);
+	}
+
+	return formatScope('repo', params);
+};
+
+export interface RpcOptions {
+	/** lexicon method NSID(s) or '*' for all */
+	lxm: LxmParam[];
+	/** audience */
+	aud: AudParam;
+}
+
+/**
+ * builds an rpc permission scope
+ * @param options rpc permission options
+ * @returns scope string like `rpc?lxm=app.bsky.feed.getFeed&aud=*`
+ */
+export const rpc = (options: RpcOptions): string => {
+	const { lxm, aud } = options;
+
+	const params = new URLSearchParams();
+	params.set('aud', aud);
+
+	for (const l of lxm) {
+		params.append('lxm', l);
+	}
+
+	return formatScope('rpc', params);
+};
+
+export interface AccountOptions {
+	/** account attribute (email, repo, status) */
+	attr: AccountAttr;
+	/** action (read or manage); defaults to read */
+	action?: AccountAction;
+}
+
+/**
+ * builds an account permission scope
+ * @param options account permission options
+ * @returns scope string like `account?attr=email` or `account?attr=email&action=manage`
+ */
+export const account = (options: AccountOptions): string => {
+	const { attr, action } = options;
+
+	const params = new URLSearchParams();
+	params.set('attr', attr);
+
+	if (action !== undefined) {
+		params.set('action', action);
+	}
+
+	return formatScope('account', params);
+};
+
+export interface BlobOptions {
+	/** MIME type(s) to accept (e.g., 'image/*', '*\/*') */
+	accept: string[];
+}
+
+/**
+ * builds a blob permission scope
+ * @param options blob permission options
+ * @returns scope string like `blob?accept=image/*`
+ */
+export const blob = (options: BlobOptions): string => {
+	const { accept } = options;
+
+	const params = new URLSearchParams();
+
+	for (const a of accept) {
+		params.append('accept', a);
+	}
+
+	return formatScope('blob', params);
+};
+
+export interface IdentityOptions {
+	/** identity attribute ('handle' or '*') */
+	attr: IdentityAttr;
+}
+
+/**
+ * builds an identity permission scope
+ * @param options identity permission options
+ * @returns scope string like `identity?attr=handle`
+ */
+export const identity = (options: IdentityOptions): string => {
+	const params = new URLSearchParams();
+	params.set('attr', options.attr);
+
+	return formatScope('identity', params);
+};
+
+export interface IncludeOptions {
+	/** lexicon NSID */
+	nsid: Nsid;
+	/** optional audience override */
+	aud?: AtprotoAudience;
+}
+
+/**
+ * builds an include scope for lexicon-defined permission sets
+ * @param options include scope options
+ * @returns scope string like `include?nsid=app.bsky.permissions&aud=did:web:bsky.app%23appview`
+ */
+export const include = (options: IncludeOptions): string => {
+	const { nsid, aud } = options;
+
+	const params = new URLSearchParams();
+	params.set('nsid', nsid);
+
+	if (aud !== undefined) {
+		params.set('aud', aud);
+	}
+
+	return formatScope('include', params);
+};
+
+// characters that should remain unencoded in scope strings
+const ALLOWED_CHARS = new Set([':', '/', '+', ',', '@', '%']);
+
+// format a scope string matching atproto oauth-scopes format
+const formatScope = (prefix: string, params: URLSearchParams): string => {
+	if (params.size === 0) {
+		return prefix;
+	}
+
+	return `${prefix}?${normalizeEncoding(params.toString())}`;
+};
+
+// normalize URL encoding to match atproto format
+// keeps : / + , @ unencoded, but # must stay as %23
+const normalizeEncoding = (value: string): string => {
+	return value.replace(/%[0-9A-F]{2}/gi, (match) => {
+		const char = decodeURIComponent(match);
+		if (ALLOWED_CHARS.has(char)) {
+			return char;
+		}
+		return match.toUpperCase();
+	});
+};

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@atcute/oauth-types",
+  "version": "0.1.0",
+  "description": "OAuth types and schemas for AT Protocol",
+  "license": "0BSD",
+  "repository": {
+    "url": "https://github.com/mary-ext/atcute",
+    "directory": "packages/oauth/types"
+  },
+  "files": [
+    "dist/",
+    "lib/",
+    "!lib/**/*.bench.ts",
+    "!lib/**/*.test.ts"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": "./dist/index.js"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@badrap/valita": "^0.4.6",
+    "@atcute/identity": "^1.1.3",
+    "@atcute/oauth-keyset": "^0.1.0",
+    "@atcute/lexicons": "^1.2.7"
+  },
+  "devDependencies": {
+    "vitest": "^4.0.16"
+  },
+  "scripts": {
+    "build": "tsgo --project tsconfig.build.json",
+    "test": "vitest",
+    "prepublish": "rm -rf dist; pnpm run build"
+  }
+}