@atproto/syntax 0.5.3 → 0.6.0-next.0

package/dist/aturi_validation.js

@@ -1,118 +1,188 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.ensureValidAtUri = ensureValidAtUri;
-exports.ensureValidAtUriRegex = ensureValidAtUriRegex;
-exports.isValidAtUri = isValidAtUri;
-const at_identifier_js_1 = require("./at-identifier.js");
-const did_js_1 = require("./did.js");
-const handle_js_1 = require("./handle.js");
-const nsid_js_1 = require("./nsid.js");
-// Human-readable constraints on ATURI:
-//   - following regular URLs, a 8KByte hard total length limit
-//   - follows ATURI docs on website
-//      - all ASCII characters, no whitespace. non-ASCII could be URL-encoded
-//      - starts "at://"
-//      - "authority" is a valid DID or a valid handle
-//      - optionally, follow "authority" with "/" and valid NSID as start of path
-//      - optionally, if NSID given, follow that with "/" and rkey
-//      - rkey path component can include URL-encoded ("percent encoded"), or:
-//          ALPHA / DIGIT / "-" / "." / "_" / "~" / ":" / "@" / "!" / "$" / "&" / "'" / "(" / ")" / "*" / "+" / "," / ";" / "="
-//          [a-zA-Z0-9._~:@!$&'\(\)*+,;=-]
-//      - rkey must have at least one char
-//      - regardless of path component, a fragment can follow  as "#" and then a JSON pointer (RFC-6901)
-function ensureValidAtUri(input) {
-    const fragmentIndex = input.indexOf('#');
-    if (fragmentIndex !== -1) {
-        if (input.charCodeAt(fragmentIndex + 1) !== 47) {
-            throw new Error('ATURI fragment must be non-empty and start with slash');
+import { isAtIdentifierString } from './at-identifier.js';
+import { failure, success } from './lib/result.js';
+import { isValidNsid } from './nsid.js';
+import { isValidRecordKey } from './recordkey.js';
+/**
+ * Type guard that checks if a value is a valid {@link AtUriString}
+ *
+ * @see {@link AtUriString}
+ */
+export function isAtUriString(input, options) {
+    return parseAtUriString(input, options).success;
+}
+/**
+ * Returns the input if it is a valid {@link AtUriString} format string, or
+ * `undefined` if it is not.
+ *
+ * @see {@link AtUriString}
+ */
+export function ifAtUriString(input, options) {
+    return isAtUriString(input, options) ? input : undefined;
+}
+/**
+ * Casts a string to an {@link AtUriString} if it is a valid AT URI format
+ * string, throwing an error if it is not.
+ *
+ * @throws InvalidAtUriError if the input string does not meet the atproto AT URI format requirements.
+ * @see {@link AtUriString}
+ */
+export function asAtUriString(input, options) {
+    assertAtUriString(input, options);
+    return input;
+}
+/**
+ * Assert the validity of an {@link AtUriString}, throwing an error if the
+ * {@link input} is not a valid AT URI.
+ *
+ * @throws InvalidAtUriError if the {@link input} is not a valid {@link AtUriString}
+ */
+export function assertAtUriString(input, options) {
+    // Optimistically use faster isAtUriString(), throwing a detailed error only
+    // in case of failure. This check, and the fact that the code after it always
+    // throws, also ensures that isAtUriString() and assertAtUriString()'s
+    // behavior are always consistent.
+    const result = parseAtUriString(input, options);
+    if (!result.success) {
+        throw new InvalidAtUriError(result.message);
+    }
+}
+/**
+ * Assert the **non-strict** validity of an {@link AtUriString}, throwing a
+ * detailed error if the {@link input} is not a valid AT URI.
+ *
+ * @throws InvalidAtUriError if the {@link input} is not a valid {@link AtUriString}
+ * @deprecated use {@link assertAtUriString} with `{ strict: false }` option instead
+ */
+export function ensureValidAtUri(input) {
+    assertAtUriString(input, { strict: false, detailed: true });
+}
+/**
+ * Assert the (non-strict!) validity of an {@link AtUriString}, throwing an
+ * error if the {@link input} is not a valid AT URI.
+ *
+ * @throws InvalidAtUriError if the {@link input} is not a valid {@link AtUriString}
+ * @deprecated use {@link assertAtUriString} with `{ strict: false }` option instead
+ */
+export function ensureValidAtUriRegex(input) {
+    assertAtUriString(input, { strict: false, detailed: false });
+}
+/**
+ * Type guard that checks if a value is a valid {@link AtUriString} format
+ * string, without enforcing strict record key validation. This is useful for
+ * cases where you want to allow a wider range of valid ATURIs, such as when
+ * validating user input or when the record key is not relevant.
+ *
+ * @deprecated use {@link isAtUriString} with `{ strict: false }` option instead
+ */
+export function isValidAtUri(input) {
+    return isAtUriString(input, { strict: false });
+}
+export class InvalidAtUriError extends Error {
+}
+const INVALID_CHAR_REGEXP = /[^a-zA-Z0-9._~:@!$&'()*+,;=%/\\[\]#?-]/;
+const AT_URI_REGEXP = /^(?<uri>at:\/\/(?<authority>[^/?#\s]+)(?:\/(?<collection>[^/?#\s]+)(?:\/(?<rkey>[^/?#\s]+))?)?(?<trailingSlash>\/)?)(?:\?(?<query>[^#\s]*))?(?:#(?<hash>[^\s]*))?$/;
+/**
+ * Parses a valid {@link AtUriString} into a {@link AtUriParts} object, or
+ * returns a failure with a detailed error message if the string is not a valid
+ * {@link AtUriString}.
+ */
+export function parseAtUriString(input, options) {
+    if (typeof input !== 'string') {
+        return failure('ATURI must be a string');
+    }
+    if (input.length > 8192) {
+        return failure('ATURI exceeds maximum length');
+    }
+    const invalidChar = input.match(INVALID_CHAR_REGEXP);
+    if (invalidChar) {
+        return failure('Disallowed characters in ATURI (ASCII)');
+    }
+    const match = input.match(AT_URI_REGEXP);
+    const groups = match?.groups;
+    if (!groups) {
+        // Regex validation failed, but we don't know exactly why. Provide more
+        // detailed error messages if the "detailed" option is set, falling back to
+        // a generic error.
+        if (options?.detailed) {
+            if (!input.startsWith('at://')) {
+                return failure('ATURI must start with "at://"');
+            }
+            if (input.includes(' ')) {
+                return failure('ATURI can not contain spaces');
+            }
+            if (input.includes('//', 5)) {
+                return failure('ATURI can not have empty path segments');
+            }
+            const pathStart = input.indexOf('/', 5); // after "at://"
+            if (pathStart !== -1) {
+                const fragmentIndex = input.indexOf('#');
+                const pathEnd = fragmentIndex !== -1 ? fragmentIndex : input.length;
+                const secondSlash = input.indexOf('/', pathStart + 1);
+                if (secondSlash !== -1 && secondSlash !== pathEnd - 1) {
+                    return failure('ATURI can not have more than two path segments');
+                }
+            }
         }
-        if (input.includes('#', fragmentIndex + 1)) {
-            throw new Error('ATURI can have at most one "#", separating fragment out');
+        return failure('ATURI does not match expected format');
+    }
+    // @NOTE Percent-encoding is allowed by the AT URI specification, but any
+    // percent-encoded characters appearing in the collection NSID or record key
+    // will effectively be rejected by the isValidNsid and isValidRecordKey
+    // validators. Since these values are defined to be plain ASCII identifiers,
+    // this legacy behavior is beneficial: it ensures that normalized
+    // (non-percent-encoded) values are always used, as prescribed by the spec.
+    if (!isAtIdentifierString(groups.authority)) {
+        return failure('ATURI has invalid authority');
+    }
+    if (groups.collection != null && !isValidNsid(groups.collection)) {
+        return failure('ATURI has invalid collection');
+    }
+    if (groups.hash != null) {
+        const result = parseJsonPointer(groups.hash, options);
+        if (result.success) {
+            groups.hash = result.value;
         }
-        // NOTE: enforcing *some* checks here for sanity. Eg, at least no whitespace
-        const fragment = input.slice(fragmentIndex + 1);
-        if (!/^\/[a-zA-Z0-9._~:@!$&')(*+,;=%[\]/-]*$/.test(fragment)) {
-            throw new Error('Disallowed characters in ATURI fragment (ASCII)');
+        else {
+            return failure(`ATURI has invalid fragment (${result.message})`);
         }
     }
-    const uri = fragmentIndex === -1 ? input : input.slice(0, fragmentIndex);
-    if (uri.length > 8 * 1024) {
-        throw new Error('ATURI is far too long');
-    }
-    if (!uri.startsWith('at://')) {
-        throw new Error('ATURI must start with "at://"');
-    }
-    // check that all chars are boring ASCII
-    if (!/^[a-zA-Z0-9._~:@!$&')(*+,;=%/-]*$/.test(uri)) {
-        throw new Error('Disallowed characters in ATURI (ASCII)');
-    }
-    const authorityEnd = uri.indexOf('/', 5);
-    const authority = authorityEnd === -1 ? uri.slice(5) : uri.slice(5, authorityEnd);
-    try {
-        (0, at_identifier_js_1.ensureValidAtIdentifier)(authority);
-    }
-    catch (cause) {
-        throw new Error('ATURI authority must be a valid handle or DID', { cause });
-    }
-    const collectionStart = authorityEnd === -1 ? -1 : authorityEnd + 1;
-    const collectionEnd = collectionStart === -1 ? -1 : uri.indexOf('/', collectionStart);
-    if (collectionStart !== -1) {
-        const collection = collectionEnd === -1
-            ? uri.slice(collectionStart)
-            : uri.slice(collectionStart, collectionEnd);
-        if (collection.length === 0) {
-            throw new Error('ATURI can not have a slash after authority without a path segment');
+    if (options?.strict !== false) {
+        if (groups.trailingSlash != null) {
+            return failure('ATURI can not have a trailing slash');
         }
-        if (!(0, nsid_js_1.isValidNsid)(collection)) {
-            throw new Error('ATURI requires first path segment (if supplied) to be valid NSID');
+        if (groups.query != null) {
+            return failure('ATURI query part is not allowed');
         }
-    }
-    const recordKeyStart = collectionEnd === -1 ? -1 : collectionEnd + 1;
-    const recordKeyEnd = recordKeyStart === -1 ? -1 : uri.indexOf('/', recordKeyStart);
-    if (recordKeyStart !== -1) {
-        if (recordKeyStart === uri.length) {
-            throw new Error('ATURI can not have a slash after collection, unless record key is provided');
+        if (groups.rkey != null && !isValidRecordKey(groups.rkey)) {
+            return failure('ATURI has invalid record key');
         }
-        // would validate rkey here, but there are basically no constraints!
-    }
-    if (recordKeyEnd !== -1) {
-        throw new Error('ATURI path can have at most two parts, and no trailing slash');
     }
+    return success(groups);
 }
-function ensureValidAtUriRegex(input) {
-    // simple regex to enforce most constraints via just regex and length.
-    // hand wrote this regex based on above constraints. whew!
-    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 = input.match(aturiRegex);
-    if (!rm || !rm.groups) {
-        throw new Error("ATURI didn't validate via regex");
-    }
-    const groups = rm.groups;
-    try {
-        (0, handle_js_1.ensureValidHandleRegex)(groups.authority);
-    }
-    catch {
-        try {
-            (0, did_js_1.ensureValidDidRegex)(groups.authority);
-        }
-        catch {
-            throw new Error('ATURI authority must be a valid handle or DID');
-        }
-    }
-    if (groups.collection && !(0, nsid_js_1.isValidNsid)(groups.collection)) {
-        throw new Error('ATURI collection path segment must be a valid NSID');
-    }
-    if (input.length > 8 * 1024) {
-        throw new Error('ATURI is far too long');
-    }
+const BASIC_JSON_POINTER_REGEXP = /^\/[a-zA-Z0-9._~:@!$&')(*+,;=%[\]/-]*$/;
+/**
+ * Checks if a string is a valid JSON pointer (RFC-6901) with the allowed chars
+ * for ATURI fragments. This is a very loose validation that only checks the
+ * basic syntax and charset.
+ */
+function parseJsonPointer(value, options) {
+    if (!BASIC_JSON_POINTER_REGEXP.test(value)) {
+        return failure('Invalid JSON pointer');
+    }
+    const result = parsePercentEncoding(value);
+    // In non-strict mode, we allow invalid percent-encoding in the fragment
+    if (!result.success && options?.strict === false) {
+        return success(value);
+    }
+    return result;
 }
-function isValidAtUri(input) {
+function parsePercentEncoding(value) {
     try {
-        ensureValidAtUri(input);
+        return success(decodeURIComponent(value));
     }
     catch {
-        return false;
+        // decodeURIComponent throws if the percent-encoding is invalid (e.g. "%FF")
+        return failure('Invalid percent-encoding');
     }
-    return true;
 }
 //# sourceMappingURL=aturi_validation.js.map

package/dist/aturi_validation.js.map

@@ -1 +1 @@
-{"version":3,"file":"aturi_validation.js","sourceRoot":"","sources":["../src/aturi_validation.ts"],"names":[],"mappings":"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","sourcesContent":["import { AtIdentifierString, ensureValidAtIdentifier } from './at-identifier.js'\nimport { ensureValidDidRegex } from './did.js'\nimport { ensureValidHandleRegex } from './handle.js'\nimport { NsidString, isValidNsid } from './nsid.js'\n\nexport type AtUriString =\n  | `at://${AtIdentifierString}`\n  | `at://${AtIdentifierString}/${NsidString}`\n  | `at://${AtIdentifierString}/${NsidString}/${string}`\n\n// Human-readable constraints on ATURI:\n//   - following regular URLs, a 8KByte hard total length limit\n//   - follows ATURI docs on website\n//      - all ASCII characters, no whitespace. non-ASCII could be URL-encoded\n//      - starts \"at://\"\n//      - \"authority\" is a valid DID or a valid handle\n//      - optionally, follow \"authority\" with \"/\" and valid NSID as start of path\n//      - optionally, if NSID given, follow that with \"/\" and rkey\n//      - rkey path component can include URL-encoded (\"percent encoded\"), or:\n//          ALPHA / DIGIT / \"-\" / \".\" / \"_\" / \"~\" / \":\" / \"@\" / \"!\" / \"$\" / \"&\" / \"'\" / \"(\" / \")\" / \"*\" / \"+\" / \",\" / \";\" / \"=\"\n//          [a-zA-Z0-9._~:@!$&'\\(\\)*+,;=-]\n//      - rkey must have at least one char\n//      - regardless of path component, a fragment can follow  as \"#\" and then a JSON pointer (RFC-6901)\n\nexport function ensureValidAtUri<I extends string>(\n  input: I,\n): asserts input is I & AtUriString {\n  const fragmentIndex = input.indexOf('#')\n  if (fragmentIndex !== -1) {\n    if (input.charCodeAt(fragmentIndex + 1) !== 47) {\n      throw new Error('ATURI fragment must be non-empty and start with slash')\n    }\n    if (input.includes('#', fragmentIndex + 1)) {\n      throw new Error('ATURI can have at most one \"#\", separating fragment out')\n    }\n\n    // NOTE: enforcing *some* checks here for sanity. Eg, at least no whitespace\n    const fragment = input.slice(fragmentIndex + 1)\n    if (!/^\\/[a-zA-Z0-9._~:@!$&')(*+,;=%[\\]/-]*$/.test(fragment)) {\n      throw new Error('Disallowed characters in ATURI fragment (ASCII)')\n    }\n  }\n\n  const uri = fragmentIndex === -1 ? input : input.slice(0, fragmentIndex)\n\n  if (uri.length > 8 * 1024) {\n    throw new Error('ATURI is far too long')\n  }\n\n  if (!uri.startsWith('at://')) {\n    throw new Error('ATURI must start with \"at://\"')\n  }\n\n  // check that all chars are boring ASCII\n  if (!/^[a-zA-Z0-9._~:@!$&')(*+,;=%/-]*$/.test(uri)) {\n    throw new Error('Disallowed characters in ATURI (ASCII)')\n  }\n\n  const authorityEnd = uri.indexOf('/', 5)\n  const authority =\n    authorityEnd === -1 ? uri.slice(5) : uri.slice(5, authorityEnd)\n  try {\n    ensureValidAtIdentifier(authority)\n  } catch (cause) {\n    throw new Error('ATURI authority must be a valid handle or DID', { cause })\n  }\n\n  const collectionStart = authorityEnd === -1 ? -1 : authorityEnd + 1\n  const collectionEnd =\n    collectionStart === -1 ? -1 : uri.indexOf('/', collectionStart)\n\n  if (collectionStart !== -1) {\n    const collection =\n      collectionEnd === -1\n        ? uri.slice(collectionStart)\n        : uri.slice(collectionStart, collectionEnd)\n\n    if (collection.length === 0) {\n      throw new Error(\n        'ATURI can not have a slash after authority without a path segment',\n      )\n    }\n    if (!isValidNsid(collection)) {\n      throw new Error(\n        'ATURI requires first path segment (if supplied) to be valid NSID',\n      )\n    }\n  }\n\n  const recordKeyStart = collectionEnd === -1 ? -1 : collectionEnd + 1\n  const recordKeyEnd =\n    recordKeyStart === -1 ? -1 : uri.indexOf('/', recordKeyStart)\n\n  if (recordKeyStart !== -1) {\n    if (recordKeyStart === uri.length) {\n      throw new Error(\n        'ATURI can not have a slash after collection, unless record key is provided',\n      )\n    }\n    // would validate rkey here, but there are basically no constraints!\n  }\n\n  if (recordKeyEnd !== -1) {\n    throw new Error(\n      'ATURI path can have at most two parts, and no trailing slash',\n    )\n  }\n}\n\nexport function ensureValidAtUriRegex<I extends string>(\n  input: I,\n): asserts input is I & AtUriString {\n  // simple regex to enforce most constraints via just regex and length.\n  // hand wrote this regex based on above constraints. whew!\n  const aturiRegex =\n    /^at:\\/\\/(?<authority>[a-zA-Z0-9._:%-]+)(\\/(?<collection>[a-zA-Z0-9-.]+)(\\/(?<rkey>[a-zA-Z0-9._~:@!$&%')(*+,;=-]+))?)?(#(?<fragment>\\/[a-zA-Z0-9._~:@!$&%')(*+,;=\\-[\\]/\\\\]*))?$/\n  const rm = input.match(aturiRegex)\n  if (!rm || !rm.groups) {\n    throw new Error(\"ATURI didn't validate via regex\")\n  }\n  const groups = rm.groups\n\n  try {\n    ensureValidHandleRegex(groups.authority)\n  } catch {\n    try {\n      ensureValidDidRegex(groups.authority)\n    } catch {\n      throw new Error('ATURI authority must be a valid handle or DID')\n    }\n  }\n\n  if (groups.collection && !isValidNsid(groups.collection)) {\n    throw new Error('ATURI collection path segment must be a valid NSID')\n  }\n\n  if (input.length > 8 * 1024) {\n    throw new Error('ATURI is far too long')\n  }\n}\n\nexport function isValidAtUri<I extends string>(\n  input: I,\n): input is I & AtUriString {\n  try {\n    ensureValidAtUri(input)\n  } catch {\n    return false\n  }\n\n  return true\n}\n"]}
+{"version":3,"file":"aturi_validation.js","sourceRoot":"","sources":["../src/aturi_validation.ts"],"names":[],"mappings":"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","sourcesContent":["import { AtIdentifierString, isAtIdentifierString } from './at-identifier.js'\nimport { Result, failure, success } from './lib/result.js'\nimport { NsidString, isValidNsid } from './nsid.js'\nimport { isValidRecordKey } from './recordkey.js'\n\nexport type AtUriStringBase =\n  | `at://${AtIdentifierString}`\n  | `at://${AtIdentifierString}/${NsidString}`\n  | `at://${AtIdentifierString}/${NsidString}/${string}`\n\nexport type AtUriStringFragment = `#/${string}`\n\n/**\n * A URI string as used to point at resources in the AT Protocol\n *\n * The full, general structure of an AT URI is:\n *\n * ```bnf\n * AT-URI = \"at://\" AUTHORITY [ PATH ] [ \"?\" QUERY ] [ \"#\" FRAGMENT ]\n * ```\n *\n * The authority part of the URI can be either a handle or a DID, indicating the\n * identity associated with the repository. In current atproto Lexicon use, the\n * query and fragment parts are not yet supported, and only a fixed pattern of\n * paths are allowed:\n *\n * ```bnf\n * AT-URI     = \"at://\" AUTHORITY [ \"/\" COLLECTION [ \"/\" RKEY ] ]\n *\n * AUTHORITY  = HANDLE | DID\n * COLLECTION = NSID\n * RKEY       = RECORD-KEY\n * ```\n *\n * The authority section is required, and should be normalized.\n *\n * AT URI strings must respect the following syntax (as prescribed by the AT\n * protocol specification):\n *\n * - The overall URI is restricted to a subset of ASCII characters\n * - For reference below, the set of unreserved characters, as defined in [RFC-3986](https://www.rfc-editor.org/rfc/rfc3986), includes alphanumeric (`A-Za-z0-9`), period, hyphen, underscore, and tilde (`.-_~`)\n * - Maximum overall length is 8 kilobytes (which may be shortened in the future)\n * - Hex-encoding of characters is permitted (but in practice not necessary and should be avoided to keep the URI normalized and human-readable)\n * - The URI scheme is `at`, and an authority part preceded with double slashes is always required. AT URIs always start with `at://`.\n * - An authority section is required and must be non-empty. the authority can be either an atproto Handle, or a DID meeting the restrictions for use with atproto. The authority part can *not* be interpreted as a host:port pair, because of the use of colon characters (`:`) in DIDs. Colons and unreserved characters should not be escaped in DIDs, but other reserved characters (including `#`, `/`, `$`, `&`, `@`) must be escaped.\n *     - Note that none of the current \"blessed\" DID methods for atproto allow these characters in DID identifiers\n * - An optional path section may follow the authority. The path may contain multiple segments separated by a single slash (`/`). Generic URI path normalization rules may be used.\n * - An optional query part is allowed, following generic URI syntax restrictions\n * - An optional fragment part is allowed, using JSON Path syntax\n *\n * @example \"at://did:plc:ewvi7nxzyoun6zhxrhs64oiz/app.bsky.actor.profile/self\"\n *\n * @see {@link https://atproto.com/specs/at-uri-scheme AT protocol - AT URI Scheme}\n */\nexport type AtUriString =\n  | AtUriStringBase\n  | `${AtUriStringBase}${AtUriStringFragment}`\n\n/**\n * Type guard that checks if a value is a valid {@link AtUriString}\n *\n * @see {@link AtUriString}\n */\nexport function isAtUriString<I>(\n  input: I,\n  options?: Omit<ParseAtUriStringOptions, 'detailed'>,\n): input is I & AtUriString {\n  return parseAtUriString(input, options).success\n}\n\n/**\n * Returns the input if it is a valid {@link AtUriString} format string, or\n * `undefined` if it is not.\n *\n * @see {@link AtUriString}\n */\nexport function ifAtUriString<I>(\n  input: I,\n  options?: Omit<ParseAtUriStringOptions, 'detailed'>,\n): undefined | (I & AtUriString) {\n  return isAtUriString(input, options) ? input : undefined\n}\n\n/**\n * Casts a string to an {@link AtUriString} if it is a valid AT URI format\n * string, throwing an error if it is not.\n *\n * @throws InvalidAtUriError if the input string does not meet the atproto AT URI format requirements.\n * @see {@link AtUriString}\n */\nexport function asAtUriString<I>(\n  input: I,\n  options?: ParseAtUriStringOptions,\n): I & AtUriString {\n  assertAtUriString(input, options)\n  return input\n}\n\n/**\n * Assert the validity of an {@link AtUriString}, throwing an error if the\n * {@link input} is not a valid AT URI.\n *\n * @throws InvalidAtUriError if the {@link input} is not a valid {@link AtUriString}\n */\nexport function assertAtUriString<I>(\n  input: I,\n  options?: ParseAtUriStringOptions,\n): asserts input is I & AtUriString {\n  // Optimistically use faster isAtUriString(), throwing a detailed error only\n  // in case of failure. This check, and the fact that the code after it always\n  // throws, also ensures that isAtUriString() and assertAtUriString()'s\n  // behavior are always consistent.\n  const result = parseAtUriString(input, options)\n  if (!result.success) {\n    throw new InvalidAtUriError(result.message)\n  }\n}\n\n/**\n * Assert the **non-strict** validity of an {@link AtUriString}, throwing a\n * detailed error if the {@link input} is not a valid AT URI.\n *\n * @throws InvalidAtUriError if the {@link input} is not a valid {@link AtUriString}\n * @deprecated use {@link assertAtUriString} with `{ strict: false }` option instead\n */\nexport function ensureValidAtUri<I>(\n  input: I,\n): asserts input is I & AtUriString {\n  assertAtUriString(input, { strict: false, detailed: true })\n}\n\n/**\n * Assert the (non-strict!) validity of an {@link AtUriString}, throwing an\n * error if the {@link input} is not a valid AT URI.\n *\n * @throws InvalidAtUriError if the {@link input} is not a valid {@link AtUriString}\n * @deprecated use {@link assertAtUriString} with `{ strict: false }` option instead\n */\nexport function ensureValidAtUriRegex<I>(\n  input: I,\n): asserts input is I & AtUriString {\n  assertAtUriString(input, { strict: false, detailed: false })\n}\n\n/**\n * Type guard that checks if a value is a valid {@link AtUriString} format\n * string, without enforcing strict record key validation. This is useful for\n * cases where you want to allow a wider range of valid ATURIs, such as when\n * validating user input or when the record key is not relevant.\n *\n * @deprecated use {@link isAtUriString} with `{ strict: false }` option instead\n */\nexport function isValidAtUri<I>(input: I): input is I & AtUriString {\n  return isAtUriString(input, { strict: false })\n}\n\nexport class InvalidAtUriError extends Error {}\n\nexport type ParseAtUriStringOptions = {\n  /**\n   * If true, the parser will enforce that the record key (rkey) part of the URI\n   * is a valid record key (validated by {@link isValidRecordKey}). If false,\n   * any non-empty string of allowed chars will be accepted as a record key.\n   *\n   * @default true\n   */\n  strict?: boolean\n\n  /**\n   * If true, the parser will return detailed error messages for why a string is\n   * not a valid AT URI. This option has no effect on the behavior of\n   * {@link isAtUriString}, which will always return false for invalid strings\n   * regardless of this option.\n   *\n   * @default false\n   */\n  detailed?: boolean\n}\n\nexport type AtUriParts = {\n  authority: AtIdentifierString\n  query?: string\n  hash?: string\n} & (\n  | { collection?: NsidString; rkey?: undefined }\n  | { collection: NsidString; rkey?: string }\n)\n\nconst INVALID_CHAR_REGEXP = /[^a-zA-Z0-9._~:@!$&'()*+,;=%/\\\\[\\]#?-]/\nconst AT_URI_REGEXP =\n  /^(?<uri>at:\\/\\/(?<authority>[^/?#\\s]+)(?:\\/(?<collection>[^/?#\\s]+)(?:\\/(?<rkey>[^/?#\\s]+))?)?(?<trailingSlash>\\/)?)(?:\\?(?<query>[^#\\s]*))?(?:#(?<hash>[^\\s]*))?$/\n\n/**\n * Parses a valid {@link AtUriString} into a {@link AtUriParts} object, or\n * returns a failure with a detailed error message if the string is not a valid\n * {@link AtUriString}.\n */\nexport function parseAtUriString(\n  input: unknown,\n  options?: ParseAtUriStringOptions,\n): Result<AtUriParts> {\n  if (typeof input !== 'string') {\n    return failure('ATURI must be a string')\n  }\n\n  if (input.length > 8192) {\n    return failure('ATURI exceeds maximum length')\n  }\n\n  const invalidChar = input.match(INVALID_CHAR_REGEXP)\n  if (invalidChar) {\n    return failure('Disallowed characters in ATURI (ASCII)')\n  }\n\n  const match = input.match(AT_URI_REGEXP)\n  const groups = match?.groups\n  if (!groups) {\n    // Regex validation failed, but we don't know exactly why. Provide more\n    // detailed error messages if the \"detailed\" option is set, falling back to\n    // a generic error.\n    if (options?.detailed) {\n      if (!input.startsWith('at://')) {\n        return failure('ATURI must start with \"at://\"')\n      }\n\n      if (input.includes(' ')) {\n        return failure('ATURI can not contain spaces')\n      }\n\n      if (input.includes('//', 5)) {\n        return failure('ATURI can not have empty path segments')\n      }\n\n      const pathStart = input.indexOf('/', 5) // after \"at://\"\n      if (pathStart !== -1) {\n        const fragmentIndex = input.indexOf('#')\n        const pathEnd = fragmentIndex !== -1 ? fragmentIndex : input.length\n        const secondSlash = input.indexOf('/', pathStart + 1)\n        if (secondSlash !== -1 && secondSlash !== pathEnd - 1) {\n          return failure('ATURI can not have more than two path segments')\n        }\n      }\n    }\n\n    return failure('ATURI does not match expected format')\n  }\n\n  // @NOTE Percent-encoding is allowed by the AT URI specification, but any\n  // percent-encoded characters appearing in the collection NSID or record key\n  // will effectively be rejected by the isValidNsid and isValidRecordKey\n  // validators. Since these values are defined to be plain ASCII identifiers,\n  // this legacy behavior is beneficial: it ensures that normalized\n  // (non-percent-encoded) values are always used, as prescribed by the spec.\n\n  if (!isAtIdentifierString(groups.authority)) {\n    return failure('ATURI has invalid authority')\n  }\n\n  if (groups.collection != null && !isValidNsid(groups.collection)) {\n    return failure('ATURI has invalid collection')\n  }\n\n  if (groups.hash != null) {\n    const result = parseJsonPointer(groups.hash, options)\n    if (result.success) {\n      groups.hash = result.value\n    } else {\n      return failure(`ATURI has invalid fragment (${result.message})`)\n    }\n  }\n\n  if (options?.strict !== false) {\n    if (groups.trailingSlash != null) {\n      return failure('ATURI can not have a trailing slash')\n    }\n\n    if (groups.query != null) {\n      return failure('ATURI query part is not allowed')\n    }\n\n    if (groups.rkey != null && !isValidRecordKey(groups.rkey)) {\n      return failure('ATURI has invalid record key')\n    }\n  }\n\n  return success(groups as AtUriParts)\n}\n\nconst BASIC_JSON_POINTER_REGEXP = /^\\/[a-zA-Z0-9._~:@!$&')(*+,;=%[\\]/-]*$/\n\n/**\n * Checks if a string is a valid JSON pointer (RFC-6901) with the allowed chars\n * for ATURI fragments. This is a very loose validation that only checks the\n * basic syntax and charset.\n */\nfunction parseJsonPointer(\n  value: string,\n  options?: { strict?: boolean },\n): Result<string> {\n  if (!BASIC_JSON_POINTER_REGEXP.test(value)) {\n    return failure('Invalid JSON pointer')\n  }\n\n  const result = parsePercentEncoding(value)\n\n  // In non-strict mode, we allow invalid percent-encoding in the fragment\n  if (!result.success && options?.strict === false) {\n    return success(value)\n  }\n\n  return result\n}\n\nfunction parsePercentEncoding(value: string): Result<string> {\n  try {\n    return success(decodeURIComponent(value))\n  } catch {\n    // decodeURIComponent throws if the percent-encoding is invalid (e.g. \"%FF\")\n    return failure('Invalid percent-encoding')\n  }\n}\n"]}

package/dist/datetime.d.ts

@@ -113,6 +113,11 @@ export declare function toDatetimeString(date: Date): DatetimeString;
  * One use-case is a consistent, sortable string. Another is to work with older
  * invalid createdAt datetimes.
  *
+ * @note This function might return different normalized strings for the same
+ * input depending on the timezone of the machine it is run on, since it will
+ * attempt to parse the input "as is" if it fails to parse with an explicit
+ * timezone.
+ *
  * @returns ISODatetimeString - a valid atproto datetime with millisecond precision (3 sub-second digits) and UTC timezone with trailing 'Z' syntax.
  * @throws InvalidDatetimeError - if the input string could not be parsed as a datetime, even with permissive parsing.
  */

package/dist/datetime.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"datetime.d.ts","sourceRoot":"","sources":["../src/datetime.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,qBAAa,oBAAqB,SAAQ,KAAK;CAAG;AAElD;;;;;;GAMG;AACH,MAAM,MAAM,iBAAiB,GAE3B,GAAG,MAAM,IAAI,MAAM,IAAI,MAAM,IAAI,MAAM,IAAI,MAAM,IAAI,MAAM,IAAI,MAAM,GAAG,CAAA;AAE1E;;;;GAIG;AACH,MAAM,WAAW,WAAY,SAAQ,IAAI;IACvC,WAAW,IAAI,iBAAiB,CAAA;CACjC;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,IAAI,GAAG,OAAO,CAAC,IAAI,IAAI,WAAW,CAKzE;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,IAAI,GAAG,WAAW,CAGrD;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,IAAI,GAAG,IAAI,IAAI,WAAW,CAE7D;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,IAAI,GAAG,WAAW,GAAG,SAAS,CAEjE;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,MAAM,cAAc,GAEtB,GAAG,MAAM,IAAI,MAAM,IAAI,MAAM,IAAI,MAAM,IAAI,MAAM,IAAI,MAAM,GAAG,GAC9D,GAAG,MAAM,IAAI,MAAM,IAAI,MAAM,IAAI,MAAM,IAAI,MAAM,IAAI,MAAM,GAAG,GAAG,GAAG,GAAG,GAAG,MAAM,IAAI,MAAM,EAAE,CAAA;AAEhG;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAAC,CAAC,EACpC,KAAK,EAAE,CAAC,GACP,OAAO,CAAC,KAAK,IAAI,CAAC,GAAG,cAAc,CAKrC;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,GAAG,CAAC,GAAG,cAAc,CAGhE;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,GAAG,KAAK,IAAI,CAAC,GAAG,cAAc,CAEzE;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,CAAC,EAChC,KAAK,EAAE,CAAC,GACP,SAAS,GAAG,CAAC,CAAC,GAAG,cAAc,CAAC,CAElC;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,IAAI,cAAc,CAEtD;AAED;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,IAAI,GAAG,cAAc,CAE3D;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,MAAM,GAAG,iBAAiB,CAkBlE;AAED;;;;;;;;GAQG;AACH,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,MAAM,GAAG,iBAAiB,CAMxE;AAGD,OAAO,EACL,oBAAoB,IAAI,mBAAmB,EAC3C,gBAAgB,IAAI,eAAe,GACpC,CAAA"}
+{"version":3,"file":"datetime.d.ts","sourceRoot":"","sources":["../src/datetime.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,qBAAa,oBAAqB,SAAQ,KAAK;CAAG;AAElD;;;;;;GAMG;AACH,MAAM,MAAM,iBAAiB,GAE3B,GAAG,MAAM,IAAI,MAAM,IAAI,MAAM,IAAI,MAAM,IAAI,MAAM,IAAI,MAAM,IAAI,MAAM,GAAG,CAAA;AAE1E;;;;GAIG;AACH,MAAM,WAAW,WAAY,SAAQ,IAAI;IACvC,WAAW,IAAI,iBAAiB,CAAA;CACjC;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,IAAI,GAAG,OAAO,CAAC,IAAI,IAAI,WAAW,CAKzE;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,IAAI,GAAG,WAAW,CAGrD;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,IAAI,GAAG,IAAI,IAAI,WAAW,CAE7D;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,IAAI,GAAG,WAAW,GAAG,SAAS,CAEjE;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,MAAM,cAAc,GAEtB,GAAG,MAAM,IAAI,MAAM,IAAI,MAAM,IAAI,MAAM,IAAI,MAAM,IAAI,MAAM,GAAG,GAC9D,GAAG,MAAM,IAAI,MAAM,IAAI,MAAM,IAAI,MAAM,IAAI,MAAM,IAAI,MAAM,GAAG,GAAG,GAAG,GAAG,GAAG,MAAM,IAAI,MAAM,EAAE,CAAA;AAEhG;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAAC,CAAC,EACpC,KAAK,EAAE,CAAC,GACP,OAAO,CAAC,KAAK,IAAI,CAAC,GAAG,cAAc,CAKrC;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,GAAG,CAAC,GAAG,cAAc,CAGhE;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,GAAG,KAAK,IAAI,CAAC,GAAG,cAAc,CAEzE;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,CAAC,EAChC,KAAK,EAAE,CAAC,GACP,SAAS,GAAG,CAAC,CAAC,GAAG,cAAc,CAAC,CAElC;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,IAAI,cAAc,CAEtD;AAED;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,IAAI,GAAG,cAAc,CAE3D;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,MAAM,GAAG,iBAAiB,CA8ClE;AAED;;;;;;;;GAQG;AACH,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,MAAM,GAAG,iBAAiB,CAMxE;AAGD,OAAO,EACL,oBAAoB,IAAI,mBAAmB,EAC3C,gBAAgB,IAAI,eAAe,GACpC,CAAA"}

package/dist/datetime.js

@@ -1,32 +1,14 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.InvalidDatetimeError = void 0;
-exports.assertAtprotoDate = assertAtprotoDate;
-exports.asAtprotoDate = asAtprotoDate;
-exports.isAtprotoDate = isAtprotoDate;
-exports.ifAtprotoDate = ifAtprotoDate;
-exports.assertDatetimeString = assertDatetimeString;
-exports.ensureValidDatetime = assertDatetimeString;
-exports.asDatetimeString = asDatetimeString;
-exports.isDatetimeString = isDatetimeString;
-exports.isValidDatetime = isDatetimeString;
-exports.ifDatetimeString = ifDatetimeString;
-exports.currentDatetimeString = currentDatetimeString;
-exports.toDatetimeString = toDatetimeString;
-exports.normalizeDatetime = normalizeDatetime;
-exports.normalizeDatetimeAlways = normalizeDatetimeAlways;
 /**
  * Indicates a date or string is not a valid representation of a datetime
  * according to the atproto
  * {@link https://atproto.com/specs/lexicon#datetime specification}.
  */
-class InvalidDatetimeError extends Error {
+export class InvalidDatetimeError extends Error {
 }
-exports.InvalidDatetimeError = InvalidDatetimeError;
 /**
  * @see {@link AtprotoDate}
  */
-function assertAtprotoDate(date) {
+export function assertAtprotoDate(date) {
     const res = parseDate(date);
     if (!res.success) {
         throw new InvalidDatetimeError(res.message);
@@ -35,20 +17,20 @@ function assertAtprotoDate(date) {
 /**
  * @see {@link AtprotoDate}
  */
-function asAtprotoDate(date) {
+export function asAtprotoDate(date) {
     assertAtprotoDate(date);
     return date;
 }
 /**
  * @see {@link AtprotoDate}
  */
-function isAtprotoDate(date) {
+export function isAtprotoDate(date) {
     return parseDate(date).success;
 }
 /**
  * @see {@link AtprotoDate}
  */
-function ifAtprotoDate(date) {
+export function ifAtprotoDate(date) {
     return isAtprotoDate(date) ? date : undefined;
 }
 /**
@@ -58,7 +40,7 @@ function ifAtprotoDate(date) {
  * @throws InvalidDatetimeError if the input string does not meet the atproto 'datetime' format requirements.
  * @see {@link DatetimeString}
  */
-function assertDatetimeString(input) {
+export function assertDatetimeString(input) {
     const result = parseString(input);
     if (!result.success) {
         throw new InvalidDatetimeError(result.message);
@@ -71,7 +53,7 @@ function assertDatetimeString(input) {
  * @throws InvalidDatetimeError if the input string does not meet the atproto 'datetime' format requirements.
  * @see {@link DatetimeString}
  */
-function asDatetimeString(input) {
+export function asDatetimeString(input) {
     assertDatetimeString(input);
     return input;
 }
@@ -80,7 +62,7 @@ function asDatetimeString(input) {
  *
  * @see {@link DatetimeString}
  */
-function isDatetimeString(input) {
+export function isDatetimeString(input) {
     return parseString(input).success;
 }
 /**
@@ -89,7 +71,7 @@ function isDatetimeString(input) {
  *
  * @see {@link DatetimeString}
  */
-function ifDatetimeString(input) {
+export function ifDatetimeString(input) {
     return isDatetimeString(input) ? input : undefined;
 }
 /**
@@ -97,7 +79,7 @@ function ifDatetimeString(input) {
  *
  * @see {@link DatetimeString}
  */
-function currentDatetimeString() {
+export function currentDatetimeString() {
     return toDatetimeString(new Date());
 }
 /**
@@ -109,7 +91,7 @@ function currentDatetimeString() {
  * @throws InvalidDatetimeError if the input date is not a valid atproto datetime (eg, it is too far in the future or past, or it normalizes to a negative year).
  * @see {@link DatetimeString}
  */
-function toDatetimeString(date) {
+export function toDatetimeString(date) {
     return asAtprotoDate(date).toISOString();
 }
 /**
@@ -122,18 +104,48 @@ function toDatetimeString(date) {
  * One use-case is a consistent, sortable string. Another is to work with older
  * invalid createdAt datetimes.
  *
+ * @note This function might return different normalized strings for the same
+ * input depending on the timezone of the machine it is run on, since it will
+ * attempt to parse the input "as is" if it fails to parse with an explicit
+ * timezone.
+ *
  * @returns ISODatetimeString - a valid atproto datetime with millisecond precision (3 sub-second digits) and UTC timezone with trailing 'Z' syntax.
  * @throws InvalidDatetimeError - if the input string could not be parsed as a datetime, even with permissive parsing.
  */
-function normalizeDatetime(dtStr) {
-    // Parse the string as is
-    const date = new Date(dtStr);
-    if (isAtprotoDate(date)) {
-        return date.toISOString();
+export function normalizeDatetime(dtStr) {
+    if (
+    // Explicit timezone offset
+    /[+-]\d\d:?\d\d/.test(dtStr) ||
+        // 'Z' timezone designator
+        /\dZ\b/.test(dtStr) ||
+        // Timezone abbreviation (eg. "EST", "PST", "UTC", "GMT", etc), as in:
+        // > Tue Mar 17 2026 16:38:44 PST (Pacific Standard Time)
+        /\b[A-Z]{3,4}\b/.test(dtStr)) {
+        // Since we do have a timezone designator, we can try parsing "as is" and
+        // should get consistent results regardless of local timezone.
+        // @NOTE NodeJS will reject dates with an un-recognized timezone designator
+        // (like "AFT"), even if we add a well-known timezone abbreviation like
+        // "UTC" or "Z".
+        const date = new Date(dtStr);
+        if (isAtprotoDate(date)) {
+            return date.toISOString();
+        }
     }
-    // if dtStr is not a valid date, try parsing again with a timezone
-    if (isNaN(date.getTime()) && !/.*(([+-]\d\d:?\d\d)|[a-zA-Z])$/.test(dtStr)) {
-        const date = new Date(`${dtStr}Z`);
+    else {
+        // If there is no timezone information, try parsing as UTC using two
+        // different syntaxes, falling back to parsing "as is".
+        const dateZ = new Date(`${dtStr}Z`);
+        if (isAtprotoDate(dateZ)) {
+            return dateZ.toISOString();
+        }
+        const dateUTC = new Date(`${dtStr} UTC`);
+        if (isAtprotoDate(dateUTC)) {
+            return dateUTC.toISOString();
+        }
+        // Despite our best efforts to parse as a consistent value, appending "Z" or
+        // " UTC" did not work, so we will try parsing "as is", which may yield
+        // different results depending on the local timezone of the machine.
+        const date = new Date(dtStr);
         if (isAtprotoDate(date)) {
             return date.toISOString();
         }
@@ -149,7 +161,7 @@ function normalizeDatetime(dtStr) {
  *
  * @see {@link normalizeDatetime}
  */
-function normalizeDatetimeAlways(dtStr) {
+export function normalizeDatetimeAlways(dtStr) {
     try {
         return normalizeDatetime(dtStr);
     }
@@ -157,6 +169,8 @@ function normalizeDatetimeAlways(dtStr) {
         return '1970-01-01T00:00:00.000Z';
     }
 }
+// Legacy exports (should we deprecate these ?)
+export { assertDatetimeString as ensureValidDatetime, isDatetimeString as isValidDatetime, };
 const failure = (m) => ({ success: false, message: m });
 const success = (v) => ({ success: true, value: v });
 /**