@atproto/syntax 0.1.0

package/README.md

@@ -0,0 +1,61 @@
+# Syntax
+
+Validation logic for AT identifiers - DIDs, Handles, NSIDs, and AT URIs
+
+## Usage
+
+```typescript
+import * as identifier from '@atproto/syntax'
+
+isValidHandle('alice.test') // returns true
+ensureValidHandle('alice.test') // returns void
+
+isValidHandle('al!ce.test') // returns false
+ensureValidHandle('al!ce.test') // throws
+
+ensureValidDid('did:method:val') // returns void
+ensureValidDid(':did:method:val') // throws
+```
+
+## NameSpaced IDs (NSID)
+
+```typescript
+import { NSID } from '@atproto/syntax'
+
+const id1 = NSID.parse('com.example.foo')
+id1.authority  // => 'example.com'
+id1.name       // => 'foo'
+id1.toString() // => 'com.example.foo'
+
+const id2 = NSID.create('example.com', 'foo')
+id2.authority  // => 'example.com'
+id2.name       // => 'foo'
+id2.toString() // => 'com.example.foo'
+
+const id3 = NSID.create('example.com', 'someRecord')
+id3.authority  // => 'example.com'
+id3.name       // => 'someRecord'
+id3.toString() // => 'com.example.someRecord'
+
+NSID.isValid('com.example.foo') // => true
+NSID.isValid('com.example.someRecord') // => true
+NSID.isValid('example.com/foo') // => false
+NSID.isValid('foo') // => false
+```
+
+## AT URI
+
+```typescript
+import { AtUri } from '@atproto/syntax'
+
+const uri = new AtUri('at://bob.com/com.example.post/1234')
+uri.protocol   // => 'at:'
+uri.origin     // => 'at://bob.com'
+uri.hostname   // => 'bob.com'
+uri.collection // => 'com.example.post'
+uri.rkey       // => '1234'
+```
+
+## License
+
+MIT

package/babel.config.js

@@ -0,0 +1 @@
+module.exports = require('../../babel.config.js')

package/build.js

@@ -0,0 +1,22 @@
+const pkgJson = require('@npmcli/package-json')
+const { nodeExternalsPlugin } = require('esbuild-node-externals')
+
+const buildShallow =
+  process.argv.includes('--shallow') || process.env.ATP_BUILD_SHALLOW === 'true'
+
+if (process.argv.includes('--update-main-to-dist')) {
+  return pkgJson
+    .load(__dirname)
+    .then((pkg) => pkg.update({ main: 'dist/index.js' }))
+    .then((pkg) => pkg.save())
+}
+
+require('esbuild').build({
+  logLevel: 'info',
+  entryPoints: ['src/index.ts'],
+  bundle: true,
+  sourcemap: true,
+  outdir: 'dist',
+  platform: 'node',
+  plugins: buildShallow ? [nodeExternalsPlugin()] : [],
+})

package/dist/aturi.d.ts

@@ -0,0 +1,22 @@
+export * from './aturi_validation';
+export declare const ATP_URI_REGEX: RegExp;
+export declare class AtUri {
+    hash: string;
+    host: string;
+    pathname: string;
+    searchParams: URLSearchParams;
+    constructor(uri: string, base?: string);
+    static make(handleOrDid: string, collection?: string, rkey?: string): AtUri;
+    get protocol(): string;
+    get origin(): string;
+    get hostname(): string;
+    set hostname(v: string);
+    get search(): string;
+    set search(v: string);
+    get collection(): string;
+    set collection(v: string);
+    get rkey(): string;
+    set rkey(v: string);
+    get href(): string;
+    toString(): string;
+}

package/dist/aturi_validation.d.ts

@@ -0,0 +1,2 @@
+export declare const ensureValidAtUri: (uri: string) => void;
+export declare const ensureValidAtUriRegex: (uri: string) => void;

package/dist/did.d.ts

@@ -0,0 +1,4 @@
+export declare const ensureValidDid: (did: string) => void;
+export declare const ensureValidDidRegex: (did: string) => void;
+export declare class InvalidDidError extends Error {
+}

package/dist/handle.d.ts

@@ -0,0 +1,16 @@
+export declare const INVALID_HANDLE = "handle.invalid";
+export declare const DISALLOWED_TLDS: string[];
+export declare const ensureValidHandle: (handle: string) => void;
+export declare const ensureValidHandleRegex: (handle: string) => void;
+export declare const normalizeHandle: (handle: string) => string;
+export declare const normalizeAndEnsureValidHandle: (handle: string) => string;
+export declare const isValidHandle: (handle: string) => boolean;
+export declare const isValidTld: (handle: string) => boolean;
+export declare class InvalidHandleError extends Error {
+}
+export declare class ReservedHandleError extends Error {
+}
+export declare class UnsupportedDomainError extends Error {
+}
+export declare class DisallowedDomainError extends Error {
+}

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export * from './handle';
+export * from './did';
+export * from './nsid';
+export * from './aturi';

package/dist/index.js

@@ -0,0 +1,483 @@
+"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/index.ts
+var src_exports = {};
+__export(src_exports, {
+  ATP_URI_REGEX: () => ATP_URI_REGEX,
+  AtUri: () => AtUri,
+  DISALLOWED_TLDS: () => DISALLOWED_TLDS,
+  DisallowedDomainError: () => DisallowedDomainError,
+  INVALID_HANDLE: () => INVALID_HANDLE,
+  InvalidDidError: () => InvalidDidError,
+  InvalidHandleError: () => InvalidHandleError,
+  InvalidNsidError: () => InvalidNsidError,
+  NSID: () => NSID,
+  ReservedHandleError: () => ReservedHandleError,
+  UnsupportedDomainError: () => UnsupportedDomainError,
+  ensureValidAtUri: () => ensureValidAtUri,
+  ensureValidAtUriRegex: () => ensureValidAtUriRegex,
+  ensureValidDid: () => ensureValidDid,
+  ensureValidDidRegex: () => ensureValidDidRegex,
+  ensureValidHandle: () => ensureValidHandle,
+  ensureValidHandleRegex: () => ensureValidHandleRegex,
+  ensureValidNsid: () => ensureValidNsid,
+  ensureValidNsidRegex: () => ensureValidNsidRegex,
+  isValidHandle: () => isValidHandle,
+  isValidTld: () => isValidTld,
+  normalizeAndEnsureValidHandle: () => normalizeAndEnsureValidHandle,
+  normalizeHandle: () => normalizeHandle
+});
+module.exports = __toCommonJS(src_exports);
+
+// src/handle.ts
+var INVALID_HANDLE = "handle.invalid";
+var DISALLOWED_TLDS = [
+  ".local",
+  ".arpa",
+  ".invalid",
+  ".localhost",
+  ".internal",
+  ".onion"
+];
+var ensureValidHandle = (handle) => {
+  if (!/^[a-zA-Z0-9.-]*$/.test(handle)) {
+    throw new InvalidHandleError(
+      "Disallowed characters in handle (ASCII letters, digits, dashes, periods only)"
+    );
+  }
+  if (handle.length > 253) {
+    throw new InvalidHandleError("Handle is too long (253 chars max)");
+  }
+  const labels = handle.split(".");
+  if (labels.length < 2) {
+    throw new InvalidHandleError("Handle domain needs at least two parts");
+  }
+  for (let i = 0; i < labels.length; i++) {
+    const l = labels[i];
+    if (l.length < 1) {
+      throw new InvalidHandleError("Handle parts can not be empty");
+    }
+    if (l.length > 63) {
+      throw new InvalidHandleError("Handle part too long (max 63 chars)");
+    }
+    if (l.endsWith("-") || l.startsWith("-")) {
+      throw new InvalidHandleError(
+        "Handle parts can not start or end with hyphens"
+      );
+    }
+    if (i + 1 == labels.length && !/^[a-zA-Z]/.test(l)) {
+      throw new InvalidHandleError(
+        "Handle final component (TLD) must start with ASCII letter"
+      );
+    }
+  }
+};
+var ensureValidHandleRegex = (handle) => {
+  if (!/^([a-zA-Z0-9]([a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?\.)+[a-zA-Z]([a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?$/.test(
+    handle
+  )) {
+    throw new InvalidHandleError("Handle didn't validate via regex");
+  }
+  if (handle.length > 253) {
+    throw new InvalidHandleError("Handle is too long (253 chars max)");
+  }
+};
+var normalizeHandle = (handle) => {
+  return handle.toLowerCase();
+};
+var normalizeAndEnsureValidHandle = (handle) => {
+  const normalized = normalizeHandle(handle);
+  ensureValidHandle(normalized);
+  return normalized;
+};
+var isValidHandle = (handle) => {
+  try {
+    ensureValidHandle(handle);
+  } catch (err) {
+    if (err instanceof InvalidHandleError) {
+      return false;
+    }
+    throw err;
+  }
+  return true;
+};
+var isValidTld = (handle) => {
+  return !DISALLOWED_TLDS.some((domain) => handle.endsWith(domain));
+};
+var InvalidHandleError = class extends Error {
+};
+var ReservedHandleError = class extends Error {
+};
+var UnsupportedDomainError = class extends Error {
+};
+var DisallowedDomainError = class extends Error {
+};
+
+// src/did.ts
+var ensureValidDid = (did) => {
+  if (!/^[a-zA-Z0-9._:%-]*$/.test(did)) {
+    throw new InvalidDidError(
+      "Disallowed characters in DID (ASCII letters, digits, and a couple other characters only)"
+    );
+  }
+  const parts = did.split(":");
+  if (parts.length < 3) {
+    throw new InvalidDidError(
+      "DID requires prefix, method, and method-specific content"
+    );
+  }
+  if (parts[0] != "did") {
+    throw new InvalidDidError('DID requires "did:" prefix');
+  }
+  if (!/^[a-z]+$/.test(parts[1])) {
+    throw new InvalidDidError("DID method must be lower-case letters");
+  }
+  if (did.endsWith(":") || did.endsWith("%")) {
+    throw new InvalidDidError('DID can not end with ":" or "%"');
+  }
+  if (did.length > 2 * 1024) {
+    throw new InvalidDidError("DID is too long (2048 chars max)");
+  }
+};
+var ensureValidDidRegex = (did) => {
+  if (!/^did:[a-z]+:[a-zA-Z0-9._:%-]*[a-zA-Z0-9._-]$/.test(did)) {
+    throw new InvalidDidError("DID didn't validate via regex");
+  }
+  if (did.length > 2 * 1024) {
+    throw new InvalidDidError("DID is too long (2048 chars max)");
+  }
+};
+var InvalidDidError = class extends Error {
+};
+
+// src/nsid.ts
+var NSID = class {
+  constructor(nsid) {
+    this.segments = [];
+    ensureValidNsid(nsid);
+    this.segments = nsid.split(".");
+  }
+  static parse(nsid) {
+    return new NSID(nsid);
+  }
+  static create(authority, name) {
+    const segments = [...authority.split(".").reverse(), name].join(".");
+    return new NSID(segments);
+  }
+  static isValid(nsid) {
+    try {
+      NSID.parse(nsid);
+      return true;
+    } catch (e) {
+      return false;
+    }
+  }
+  get authority() {
+    return this.segments.slice(0, this.segments.length - 1).reverse().join(".");
+  }
+  get name() {
+    return this.segments.at(this.segments.length - 1);
+  }
+  toString() {
+    return this.segments.join(".");
+  }
+};
+var ensureValidNsid = (nsid) => {
+  const toCheck = nsid;
+  if (!/^[a-zA-Z0-9.-]*$/.test(toCheck)) {
+    throw new InvalidNsidError(
+      "Disallowed characters in NSID (ASCII letters, digits, dashes, periods only)"
+    );
+  }
+  if (toCheck.length > 253 + 1 + 63) {
+    throw new InvalidNsidError("NSID is too long (317 chars max)");
+  }
+  const labels = toCheck.split(".");
+  if (labels.length < 3) {
+    throw new InvalidNsidError("NSID needs at least three parts");
+  }
+  for (let i = 0; i < labels.length; i++) {
+    const l = labels[i];
+    if (l.length < 1) {
+      throw new InvalidNsidError("NSID parts can not be empty");
+    }
+    if (l.length > 63) {
+      throw new InvalidNsidError("NSID part too long (max 63 chars)");
+    }
+    if (l.endsWith("-") || l.startsWith("-")) {
+      throw new InvalidNsidError("NSID parts can not start or end with hyphen");
+    }
+    if (/^[0-9]/.test(l) && i == 0) {
+      throw new InvalidNsidError("NSID first part may not start with a digit");
+    }
+    if (!/^[a-zA-Z]+$/.test(l) && i + 1 == labels.length) {
+      throw new InvalidNsidError("NSID name part must be only letters");
+    }
+  }
+};
+var ensureValidNsidRegex = (nsid) => {
+  if (!/^[a-zA-Z]([a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?(\.[a-zA-Z0-9]([a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?)+(\.[a-zA-Z]([a-zA-Z]{0,61}[a-zA-Z])?)$/.test(
+    nsid
+  )) {
+    throw new InvalidNsidError("NSID didn't validate via regex");
+  }
+  if (nsid.length > 253 + 1 + 63) {
+    throw new InvalidNsidError("NSID is too long (317 chars max)");
+  }
+};
+var InvalidNsidError = class extends Error {
+};
+
+// src/aturi_validation.ts
+var ensureValidAtUri = (uri) => {
+  const uriParts = uri.split("#");
+  if (uriParts.length > 2) {
+    throw new Error('ATURI can have at most one "#", separating fragment out');
+  }
+  const fragmentPart = uriParts[1] || null;
+  uri = uriParts[0];
+  if (!/^[a-zA-Z0-9._~:@!$&')(*+,;=%/-]*$/.test(uri)) {
+    throw new Error("Disallowed characters in ATURI (ASCII)");
+  }
+  const parts = uri.split("/");
+  if (parts.length >= 3 && (parts[0] != "at:" || parts[1].length != 0)) {
+    throw new Error('ATURI must start with "at://"');
+  }
+  if (parts.length < 3) {
+    throw new Error("ATURI requires at least method and authority sections");
+  }
+  try {
+    ensureValidHandle(parts[2]);
+  } catch {
+    try {
+      ensureValidDid(parts[2]);
+    } catch {
+      throw new Error("ATURI authority must be a valid handle or DID");
+    }
+  }
+  if (parts.length >= 4) {
+    if (parts[3].length == 0) {
+      throw new Error(
+        "ATURI can not have a slash after authority without a path segment"
+      );
+    }
+    try {
+      ensureValidNsid(parts[3]);
+    } catch {
+      throw new Error(
+        "ATURI requires first path segment (if supplied) to be valid NSID"
+      );
+    }
+  }
+  if (parts.length >= 5) {
+    if (parts[4].length == 0) {
+      throw new Error(
+        "ATURI can not have a slash after collection, unless record key is provided"
+      );
+    }
+  }
+  if (parts.length >= 6) {
+    throw new Error(
+      "ATURI path can have at most two parts, and no trailing slash"
+    );
+  }
+  if (uriParts.length >= 2 && fragmentPart == null) {
+    throw new Error("ATURI fragment must be non-empty and start with slash");
+  }
+  if (fragmentPart != null) {
+    if (fragmentPart.length == 0 || fragmentPart[0] != "/") {
+      throw new Error("ATURI fragment must be non-empty and start with slash");
+    }
+    if (!/^\/[a-zA-Z0-9._~:@!$&')(*+,;=%[\]/-]*$/.test(fragmentPart)) {
+      throw new Error("Disallowed characters in ATURI fragment (ASCII)");
+    }
+  }
+  if (uri.length > 8 * 1024) {
+    throw new Error("ATURI is far too long");
+  }
+};
+var ensureValidAtUriRegex = (uri) => {
+  const aturiRegex = /^at:\/\/(?<authority>[a-zA-Z0-9._:%-]+)(\/(?<collection>[a-zA-Z0-9-.]+)(\/(?<rkey>[a-zA-Z0-9._~:@!$&%')(*+,;=-]+))?)?(#(?<fragment>\/[a-zA-Z0-9._~:@!$&%')(*+,;=\-[\]/\\]*))?$/;
+  const rm = uri.match(aturiRegex);
+  if (!rm || !rm.groups) {
+    throw new Error("ATURI didn't validate via regex");
+  }
+  const groups = rm.groups;
+  try {
+    ensureValidHandleRegex(groups.authority);
+  } catch {
+    try {
+      ensureValidDidRegex(groups.authority);
+    } catch {
+      throw new Error("ATURI authority must be a valid handle or DID");
+    }
+  }
+  if (groups.collection) {
+    try {
+      ensureValidNsidRegex(groups.collection);
+    } catch {
+      throw new Error("ATURI collection path segment must be a valid NSID");
+    }
+  }
+  if (uri.length > 8 * 1024) {
+    throw new Error("ATURI is far too long");
+  }
+};
+
+// src/aturi.ts
+var ATP_URI_REGEX = /^(at:\/\/)?((?:did:[a-z0-9:%-]+)|(?:[a-z0-9][a-z0-9.:-]*))(\/[^?#\s]*)?(\?[^#\s]+)?(#[^\s]+)?$/i;
+var RELATIVE_REGEX = /^(\/[^?#\s]*)?(\?[^#\s]+)?(#[^\s]+)?$/i;
+var AtUri = class {
+  constructor(uri, base) {
+    let parsed;
+    if (base) {
+      parsed = parse(base);
+      if (!parsed) {
+        throw new Error(`Invalid at uri: ${base}`);
+      }
+      const relativep = parseRelative(uri);
+      if (!relativep) {
+        throw new Error(`Invalid path: ${uri}`);
+      }
+      Object.assign(parsed, relativep);
+    } else {
+      parsed = parse(uri);
+      if (!parsed) {
+        throw new Error(`Invalid at uri: ${uri}`);
+      }
+    }
+    this.hash = parsed.hash;
+    this.host = parsed.host;
+    this.pathname = parsed.pathname;
+    this.searchParams = parsed.searchParams;
+  }
+  static make(handleOrDid, collection, rkey) {
+    let str = handleOrDid;
+    if (collection)
+      str += "/" + collection;
+    if (rkey)
+      str += "/" + rkey;
+    return new AtUri(str);
+  }
+  get protocol() {
+    return "at:";
+  }
+  get origin() {
+    return `at://${this.host}`;
+  }
+  get hostname() {
+    return this.host;
+  }
+  set hostname(v) {
+    this.host = v;
+  }
+  get search() {
+    return this.searchParams.toString();
+  }
+  set search(v) {
+    this.searchParams = new URLSearchParams(v);
+  }
+  get collection() {
+    return this.pathname.split("/").filter(Boolean)[0] || "";
+  }
+  set collection(v) {
+    const parts = this.pathname.split("/").filter(Boolean);
+    parts[0] = v;
+    this.pathname = parts.join("/");
+  }
+  get rkey() {
+    return this.pathname.split("/").filter(Boolean)[1] || "";
+  }
+  set rkey(v) {
+    const parts = this.pathname.split("/").filter(Boolean);
+    if (!parts[0])
+      parts[0] = "undefined";
+    parts[1] = v;
+    this.pathname = parts.join("/");
+  }
+  get href() {
+    return this.toString();
+  }
+  toString() {
+    let path = this.pathname || "/";
+    if (!path.startsWith("/")) {
+      path = `/${path}`;
+    }
+    let qs = this.searchParams.toString();
+    if (qs && !qs.startsWith("?")) {
+      qs = `?${qs}`;
+    }
+    let hash = this.hash;
+    if (hash && !hash.startsWith("#")) {
+      hash = `#${hash}`;
+    }
+    return `at://${this.host}${path}${qs}${hash}`;
+  }
+};
+function parse(str) {
+  const match = ATP_URI_REGEX.exec(str);
+  if (match) {
+    return {
+      hash: match[5] || "",
+      host: match[2] || "",
+      pathname: match[3] || "",
+      searchParams: new URLSearchParams(match[4] || "")
+    };
+  }
+  return void 0;
+}
+function parseRelative(str) {
+  const match = RELATIVE_REGEX.exec(str);
+  if (match) {
+    return {
+      hash: match[3] || "",
+      pathname: match[1] || "",
+      searchParams: new URLSearchParams(match[2] || "")
+    };
+  }
+  return void 0;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  ATP_URI_REGEX,
+  AtUri,
+  DISALLOWED_TLDS,
+  DisallowedDomainError,
+  INVALID_HANDLE,
+  InvalidDidError,
+  InvalidHandleError,
+  InvalidNsidError,
+  NSID,
+  ReservedHandleError,
+  UnsupportedDomainError,
+  ensureValidAtUri,
+  ensureValidAtUriRegex,
+  ensureValidDid,
+  ensureValidDidRegex,
+  ensureValidHandle,
+  ensureValidHandleRegex,
+  ensureValidNsid,
+  ensureValidNsidRegex,
+  isValidHandle,
+  isValidTld,
+  normalizeAndEnsureValidHandle,
+  normalizeHandle
+});
+//# sourceMappingURL=index.js.map