@astryxdesign/core 0.6.3-canary.f22695a → 0.6.3

package/src/theme/declarationBoundary.ts

@@ -1,347 +0,0 @@
-// Copyright (c) Meta Platforms, Inc. and affiliates.
-
-/**
- * @file Declaration boundary scanner
- *
- * Decides whether a consumer-supplied property name and value can be emitted
- * as exactly one CSS declaration, `name: value;`, without the value ending
- * the declaration early or swallowing what follows it. Theme definitions are
- * code, but apps assemble them from stored input (brand colors,
- * white-labeling), so the generated stylesheet must never extend beyond the
- * declarations it means to emit.
- *
- * The scanner follows the CSS Syntax Module Level 3 tokenizer for everything
- * that decides where a declaration ends: strings with backslash escapes and
- * line continuations, comments, `url()` with an unquoted body, escaped code
- * points outside strings, and `()`, `[]`, `{}` block nesting. Inside any of
- * those a `;` or a brace is inert, exactly as a browser reads it, so a `data:`
- * URI, `Gill\ Sans`, or a closed comment passes through byte-identically.
- * Only what a browser would read as the end of the declaration or rule is
- * rejected: an unnested `;`, `{` or `}`, an unbalanced closer, and anything
- * left open at the end of the value (a string, comment, block, or url whose
- * closer would then be the generator's own `;` or `}`). A `bad-string` or
- * `bad-url` token is rejected as well: the browser would discard the
- * declaration anyway, and a diagnostic beats a silent no-op.
- *
- * @input A property name or a declaration value as authored in a theme
- * @output `null` when it can be emitted, otherwise the reason it cannot
- * @position packages/core/src/theme/declarationBoundary.ts
- */
-
-/** Newline per CSS Syntax §4.2 (after preprocessing, CR and FF are newlines). */
-function isNewline(ch: string): boolean {
-  return ch === '\n' || ch === '\r' || ch === '\f';
-}
-
-function isWhitespace(ch: string): boolean {
-  return ch === ' ' || ch === '\t' || isNewline(ch);
-}
-
-function isHexDigit(ch: string): boolean {
-  return /^[0-9a-fA-F]$/.test(ch);
-}
-
-/** Name-start code point: letter, underscore, or any non-ASCII code point. */
-function isNameStart(ch: string): boolean {
-  return /^[A-Za-z_]$/.test(ch) || ch.charCodeAt(0) >= 0x80;
-}
-
-function isNameChar(ch: string): boolean {
-  return isNameStart(ch) || /^[0-9-]$/.test(ch);
-}
-
-/** CSS Syntax §3.3 preprocessing, for scanning only; emitted bytes stay intact. */
-function preprocess(input: string): string {
-  return input.replace(/\r\n?|\f/g, '\n').replace(/\0/g, '\uFFFD');
-}
-
-/** Non-printable code points make an unquoted url() a bad-url token. */
-// eslint-disable-next-line no-control-regex -- these code points are the subject
-const NON_PRINTABLE = /[\x01-\x08\x0b\x0e-\x1f\x7f]/;
-
-/** "Check if two code points are a valid escape" (§4.3.8). */
-function isValidEscape(input: string, pos: number): boolean {
-  return (
-    input[pos] === '\\' && pos + 1 < input.length && !isNewline(input[pos + 1])
-  );
-}
-
-/** "Check if three code points would start an ident sequence" (§4.3.9). */
-function startsIdent(input: string, pos: number): boolean {
-  const ch = input[pos];
-  if (ch === '-') {
-    const next = input[pos + 1];
-    return (
-      next !== undefined &&
-      (next === '-' || isNameStart(next) || isValidEscape(input, pos + 1))
-    );
-  }
-  if (ch === '\\') {
-    return isValidEscape(input, pos);
-  }
-  return ch !== undefined && isNameStart(ch);
-}
-
-/**
- * "Consume an escaped code point" (§4.3.7), positioned after the backslash.
- * Returns the position after the escape. A hex escape takes up to six hex
- * digits plus one optional whitespace; anything else takes one code point.
- */
-function consumeEscape(input: string, pos: number): number {
-  if (isHexDigit(input[pos])) {
-    let end = pos;
-    while (end < input.length && end - pos < 6 && isHexDigit(input[end])) {
-      end++;
-    }
-    if (end < input.length && isWhitespace(input[end])) {
-      end++;
-    }
-    return end;
-  }
-  // A surrogate pair is one code point.
-  const code = input.codePointAt(pos) ?? 0;
-  return pos + (code > 0xffff ? 2 : 1);
-}
-
-/**
- * "Consume an ident sequence" (§4.3.11) starting at `pos`. Returns the
- * position after it and the decoded name (escapes resolved, for the
- * case-insensitive `url` check; hex escapes decode to their code point).
- */
-function consumeIdent(input: string, pos: number): {end: number; name: string} {
-  let name = '';
-  let i = pos;
-  while (i < input.length) {
-    const ch = input[i];
-    if (isNameChar(ch)) {
-      name += ch;
-      i++;
-    } else if (isValidEscape(input, i)) {
-      const end = consumeEscape(input, i + 1);
-      if (isHexDigit(input[i + 1])) {
-        const hex = input.slice(i + 1, end).trim();
-        const code = parseInt(hex, 16);
-        name +=
-          code === 0 || code > 0x10ffff || (code >= 0xd800 && code <= 0xdfff)
-            ? '\uFFFD'
-            : String.fromCodePoint(code);
-      } else {
-        name += input.slice(i + 1, end);
-      }
-      i = end;
-    } else {
-      break;
-    }
-  }
-  return {end: i, name};
-}
-
-/**
- * "Consume a string token" (§4.3.5), positioned at the opening quote.
- * Returns the position after the closing quote, or a rejection reason.
- */
-function consumeString(
-  input: string,
-  pos: number,
-): {end: number} | {reason: string} {
-  const quote = input[pos];
-  let i = pos + 1;
-  while (i < input.length) {
-    const ch = input[i];
-    if (ch === quote) {
-      return {end: i + 1};
-    }
-    if (isNewline(ch)) {
-      // A raw newline ends the string as a bad-string token; the browser
-      // discards the declaration, so a diagnostic is more useful than
-      // reasoning about where that leaves the next `;`.
-      return {reason: 'a newline inside a quoted string makes a bad string'};
-    }
-    if (ch === '\\') {
-      if (i + 1 >= input.length) {
-        break;
-      }
-      // Escaped newline is a line continuation; any other escape consumes
-      // the escaped code point (so `\"` never closes the string).
-      i = isNewline(input[i + 1]) ? i + 2 : consumeEscape(input, i + 1);
-      continue;
-    }
-    i++;
-  }
-  return {
-    reason: `an unclosed ${quote} string would swallow the rest of the rule`,
-  };
-}
-
-/**
- * "Consume a url token" (§4.3.6), positioned after `url(` and any leading
- * whitespace, with a non-quote next code point. Returns the position after
- * the closing `)`, or a rejection reason (bad-url or unclosed).
- */
-function consumeUrl(
-  input: string,
-  pos: number,
-): {end: number} | {reason: string} {
-  let i = pos;
-  while (i < input.length) {
-    const ch = input[i];
-    if (ch === ')') {
-      return {end: i + 1};
-    }
-    if (isWhitespace(ch)) {
-      while (i < input.length && isWhitespace(input[i])) {
-        i++;
-      }
-      if (i >= input.length) {
-        break;
-      }
-      if (input[i] === ')') {
-        return {end: i + 1};
-      }
-      return {reason: 'whitespace inside an unquoted url() makes a bad url'};
-    }
-    if (NON_PRINTABLE.test(ch)) {
-      return {reason: 'a non-printable character inside url() makes a bad url'};
-    }
-    if (ch === '"' || ch === "'" || ch === '(') {
-      return {
-        reason: `"${ch}" inside an unquoted url() makes a bad url; quote the URL instead`,
-      };
-    }
-    if (ch === '\\') {
-      if (!isValidEscape(input, i)) {
-        return {reason: 'a stray backslash inside url() makes a bad url'};
-      }
-      i = consumeEscape(input, i + 1);
-      continue;
-    }
-    i++;
-  }
-  return {reason: 'an unclosed url( would swallow the rest of the rule'};
-}
-
-const CLOSER: Record<string, string> = {'(': ')', '[': ']', '{': '}'};
-
-/**
- * Why `value` cannot be emitted as the value of one declaration, or `null`
- * when it can. Valid CSS a browser keeps inside one declaration always
- * returns `null`; see the file header for the exact rules.
- */
-export function checkDeclarationValue(input: string): string | null {
-  const value = preprocess(input);
-  const open: string[] = [];
-  let i = 0;
-  while (i < value.length) {
-    const ch = value[i];
-
-    if (ch === '/' && value[i + 1] === '*') {
-      const close = value.indexOf('*/', i + 2);
-      if (close === -1) {
-        return 'an unclosed /* comment would swallow the rest of the rule';
-      }
-      i = close + 2;
-      continue;
-    }
-
-    if (ch === '"' || ch === "'") {
-      const result = consumeString(value, i);
-      if ('reason' in result) {
-        return result.reason;
-      }
-      i = result.end;
-      continue;
-    }
-
-    if (startsIdent(value, i)) {
-      const ident = consumeIdent(value, i);
-      i = ident.end;
-      if (value[i] === '(' && ident.name.toLowerCase() === 'url') {
-        let j = i + 1;
-        while (j < value.length && isWhitespace(value[j])) {
-          j++;
-        }
-        if (value[j] === '"' || value[j] === "'") {
-          // `url("...")` is an ordinary function token; the string and the
-          // closing paren are handled by the loop.
-          open.push(')');
-          i = i + 1;
-          continue;
-        }
-        const result = consumeUrl(value, j);
-        if ('reason' in result) {
-          return result.reason;
-        }
-        i = result.end;
-      }
-      continue;
-    }
-
-    if (ch === '\\') {
-      if (i + 1 >= value.length) {
-        // `\` followed by the generator's own `;` would escape it.
-        return 'a trailing backslash would escape the declaration terminator';
-      }
-      // `\` + newline is not an escape: the backslash is a delim and the
-      // newline is whitespace. Anything else escapes the next code point.
-      i = isNewline(value[i + 1]) ? i + 1 : consumeEscape(value, i + 1);
-      continue;
-    }
-
-    if (ch === '(' || ch === '[' || ch === '{') {
-      if (ch === '{' && open.length === 0) {
-        return 'an unquoted "{" would open a nested block';
-      }
-      open.push(CLOSER[ch]);
-      i++;
-      continue;
-    }
-
-    if (ch === ')' || ch === ']' || ch === '}') {
-      if (open.length === 0) {
-        return ch === '}'
-          ? 'an unquoted "}" would close the rule'
-          : `an unbalanced "${ch}" has nothing to close`;
-      }
-      const expected = open.pop();
-      if (expected !== ch) {
-        return `"${ch}" does not close the open "${expected === ')' ? '(' : expected === ']' ? '[' : '{'}"`;
-      }
-      i++;
-      continue;
-    }
-
-    if (ch === ';' && open.length === 0) {
-      return 'an unquoted ";" would end the declaration';
-    }
-
-    i++;
-  }
-
-  if (open.length > 0) {
-    const closer = open[open.length - 1];
-    const opener = closer === ')' ? '(' : closer === ']' ? '[' : '{';
-    return `an unclosed "${opener}" would swallow the rest of the rule`;
-  }
-  return null;
-}
-
-/**
- * Why `name` cannot be emitted as a declaration's property name, or `null`
- * when it can. A property name is one CSS ident sequence: a standard
- * property (`color`), a vendor-prefixed one (`-webkit-line-clamp`), or a
- * custom property (`--brand-accent`, `--_internal`). Escapes are allowed
- * because an ident allows them. Whether the name means anything to the
- * browser is not this check's concern; only that it cannot end the
- * declaration or leak a second one.
- */
-export function checkDeclarationName(input: string): string | null {
-  const name = preprocess(input);
-  if (name.length === 0 || !startsIdent(name, 0)) {
-    return 'a property name must be a CSS identifier';
-  }
-  const {end} = consumeIdent(name, 0);
-  if (end !== name.length) {
-    return `a property name must be one CSS identifier; "${name[end]}" cannot appear in one`;
-  }
-  return null;
-}

package/src/utils/safeUrl.test.ts

@@ -1,88 +0,0 @@
-// Copyright (c) Meta Platforms, Inc. and affiliates.
-
-import {describe, expect, it} from 'vitest';
-import {isSafeDestination, isSafeUrl, sanitizeUrl} from './safeUrl';
-
-// Expectations come from the navigation contract, not another policy helper.
-const accepted = [
-  'https://example.com/a?b=c#d',
-  'http://example.com',
-  '//example.com/protocol-relative',
-  '/relative/path',
-  'relative/path',
-  '#fragment',
-  'mailto:a@example.com',
-  'tel:+1234567890',
-  'custom:open/document',
-  'data:image/png;base64,iVBORw0KGgo=',
-  'data:text/plain,download',
-];
-const rejected = [
-  'javascript:alert(1)',
-  'JaVaScRiPt:alert(1)',
-  '  javascript:alert(1)',
-  'vbscript:MsgBox(1)',
-  'data:text/html,<script>alert(1)</script>',
-  'DATA:TEXT/HTML;base64,PHNjcmlwdD4=',
-  'java\tscript:alert(1)',
-  'java\nscript:alert(1)',
-  '\x00javascript:alert(1)',
-  'java\x7fscript:alert(1)',
-];
-
-describe('navigation strings', () => {
-  it.each(accepted)('accepts %s', url => {
-    expect(isSafeUrl(url)).toBe(true);
-    expect(isSafeDestination(url)).toBe(true);
-    expect(sanitizeUrl(url)).toBe(url);
-  });
-  it.each(rejected)('rejects %s', url => {
-    expect(isSafeUrl(url)).toBe(false);
-    expect(isSafeDestination(url)).toBe(false);
-    expect(sanitizeUrl(url)).toBeNull();
-  });
-  it('normalizes accepted strings only when requested', () => {
-    expect(sanitizeUrl('  /docs\n')).toBe('/docs');
-    expect(sanitizeUrl('/do\x00cs')).toBe('/docs');
-  });
-});
-
-describe('structured destinations', () => {
-  it.each([
-    {pathname: '/docs', search: '?q=1', hash: '#a'},
-    {href: 'https://example.com'},
-    {protocol: 'https:', hostname: 'example.com', pathname: '/docs'},
-    {protocol: 'custom', pathname: 'document'},
-    {protocol: 'mailto:', pathname: 'a@example.com'},
-    {protocol: 'data:', pathname: 'image/png;base64,aA=='},
-    {search: '?page=2'},
-    {hash: '#section'},
-    {},
-    new URL('https://example.com/docs'),
-    undefined,
-    null,
-  ])('accepts supported destination %j', destination => {
-    expect(isSafeDestination(destination)).toBe(true);
-  });
-  it.each([
-    {pathname: 'javascript:alert(1)'},
-    {pathname: 'java\x00script:alert(1)'},
-    {href: 'vbscript:MsgBox(1)'},
-    {pathname: '/ok', href: 'javascript:1'},
-    {protocol: 'javascript:', pathname: 'alert(1)'},
-    {protocol: 'javascript', pathname: 'alert(1)'},
-    {protocol: ' JaVa\tsCrIpT ', pathname: 'alert(1)'},
-    {protocol: 'vbscript', pathname: 'MsgBox(1)'},
-    {protocol: 'data:', pathname: 'text/html,<b>x</b>'},
-    {protocol: 'data', pathname: 'TEXT/HTML;base64,PGI+eDwvYj4='},
-    {protocol: 'data:', host: 'text/', pathname: 'html,<b>x</b>'},
-    {protocol: 'data:', hostname: 'text/html,<b>x</b>'},
-    {href: '/safe', protocol: 'javascript:'},
-    new URL('javascript:alert(1)'),
-    {pathname: 42},
-    {protocol: {toString: (): string => 'javascript:'}},
-    3,
-  ])('rejects blocked or unsupported destination %j', destination => {
-    expect(isSafeDestination(destination)).toBe(false);
-  });
-});

package/src/utils/safeUrl.ts

@@ -1,85 +0,0 @@
-// Copyright (c) Meta Platforms, Inc. and affiliates.
-
-/**
- * @file safeUrl.ts
- * @input Navigation strings or supported structured router destinations
- * @output The shared blocked-scheme decision, without rewriting accepted inputs
- * @position Core navigation policy; embedded-resource policy is separate
- */
-
-function normalizeUrl(url: string): string {
-  // eslint-disable-next-line no-control-regex -- inspect schemes without browser-ignored controls
-  return url.replace(/[\x00-\x1f\x7f]/g, '').trim();
-}
-
-/** Return a normalized navigation URL, or null for a blocked scheme. */
-export function sanitizeUrl(url: string): string | null {
-  const normalized = normalizeUrl(url);
-  const lower = normalized.toLowerCase();
-  if (
-    lower.startsWith('javascript:') ||
-    lower.startsWith('vbscript:') ||
-    lower.startsWith('data:text/html')
-  ) {
-    return null;
-  }
-  return normalized;
-}
-
-/** Inspect a navigation string without changing the value used by its sink. */
-export function isSafeUrl(url: string): boolean {
-  return sanitizeUrl(url) !== null;
-}
-
-/**
- * Inspect React Router paths, Next.js URL objects, and URL instances without
- * serializing or replacing the object handed to the router. Search/query/hash
- * are route-relative data, not schemes. Absent destinations remain absent.
- */
-export function isSafeDestination(destination: unknown): boolean {
-  if (destination == null) {
-    return true;
-  }
-  if (typeof destination === 'string') {
-    return isSafeUrl(destination);
-  }
-  if (typeof destination !== 'object') {
-    return false;
-  }
-
-  const {pathname, href, protocol, host, hostname} = destination as {
-    pathname?: unknown;
-    href?: unknown;
-    protocol?: unknown;
-    host?: unknown;
-    hostname?: unknown;
-  };
-  for (const field of [pathname, href, protocol, host, hostname]) {
-    if (field != null && typeof field !== 'string') {
-      return false;
-    }
-  }
-  if (typeof pathname === 'string' && !isSafeUrl(pathname)) {
-    return false;
-  }
-  if (typeof href === 'string' && !isSafeUrl(href)) {
-    return false;
-  }
-  if (typeof protocol === 'string' && protocol !== '') {
-    // URL-object formatters accept a protocol with or without its colon and
-    // can assemble a data media type from the host and pathname fields.
-    const normalizedProtocol = normalizeUrl(protocol);
-    const prefix = normalizedProtocol.endsWith(':')
-      ? normalizedProtocol
-      : `${normalizedProtocol}:`;
-    if (!isSafeUrl(prefix)) {
-      return false;
-    }
-    const body = (host || hostname || '') as string;
-    const path = typeof pathname === 'string' ? pathname : '';
-    if (!isSafeUrl(`${prefix}${body}${path}`)) {
-      return false;
-    }
-  }
-  return true;
-}