DEV Community

Nekoautomata Miki
Nekoautomata Miki

Posted on

An .ics file can name a time without naming your time zone: inspect imports with InviteLens

#opensource #privacy #security #node

An iCalendar invitation can contain a date and clock time while leaving the time zone to whichever calendar application opens it.

That is not the same representation as UTC, a named TZID, or an all-day DATE. The values can look similar in plain text, yet they ask an importer to interpret different things.

InviteLens 0.1.0 is a local preflight for that representation layer. It explains the time forms and repeated revision identifiers present in one supplied .ics file before an import adds a snapshot to a calendar.

It does not import the file, contact a calendar account, expand recurrence, or predict what Google Calendar, Outlook, Apple Calendar, a server, or a particular local time-zone database will do.

Four values that should not be treated as interchangeable

RFC 5545 distinguishes several time forms. These examples all describe values in an event, but they do not carry the same interpretation contract.

UTC 

DTSTART:20260721T130000Z
Enter fullscreen mode Exit fullscreen mode

The trailing Z declares UTC.

Named time zone 

DTSTART;TZID=Europe/Paris:20260721T150000
Enter fullscreen mode Exit fullscreen mode

The value is tied to a TZID. An interoperable file should provide a matching VTIMEZONE definition rather than assume every importer maps the identifier the same way.

Floating local time 

DTSTART:20260721T150000
Enter fullscreen mode Exit fullscreen mode

There is no Z and no TZID. This is a floating time. RFC 5545 defines it independently of a specific time zone, so an importing viewer can interpret it in its own local zone.

All-day date 

DTSTART;VALUE=DATE:20260721
DTEND;VALUE=DATE:20260722
Enter fullscreen mode Exit fullscreen mode

These are dates rather than date-times. The DTEND is exclusive: this example represents one included date, 21 July, not a two-day event ending at the close of 22 July.

InviteLens labels these forms instead of converting them into one guessed universal timestamp.

Run a local inspection

Install from the Codeberg npm registry:

npm install --global invitelens@0.1.0 \
  --registry=https://codeberg.org/api/packages/automa-tan/npm/
Enter fullscreen mode Exit fullscreen mode

Then inspect one file:

invitelens invite.ics
Enter fullscreen mode Exit fullscreen mode

For machine-readable output and a review gate:

invitelens invite.ics \
  --format json \
  --output invite-report.json \
  --strict
Enter fullscreen mode Exit fullscreen mode

A report file is created with mode 0600, refuses overwrite, and is completely written before --strict returns status 1 for modeled errors. That means a correctly failed CI step can retain the evidence that explains the failure.

The bundled synthetic demo contains three events: a UTC meeting, a floating reminder, and an all-day event with an exclusive end date.

invitelens node_modules/invitelens/examples/safe-demo.ics
Enter fullscreen mode Exit fullscreen mode

The report separates event declarations from findings. It does not silently rewrite the source or choose a replacement value.

Time-zone declarations are part of the file contract

A TZID reference without a matching VTIMEZONE is not enough for InviteLens to claim that the represented instant is portable.

The tool reports undeclared identifiers and duplicate or invalid VTIMEZONE declarations. It still does not map proprietary identifiers or certify a specific importer's fallback behavior. Those are application and environment questions outside the file-level model.

It also checks that DTSTART and DTEND use compatible DATE versus DATE-TIME forms. When the frames differ—for example UTC start and named-zone end—it warns that elapsed ordering was not evaluated instead of comparing the raw strings as if they shared one frame.

Repeated UID does not automatically mean “take the last event”

Calendar updates commonly reuse a UID and change SEQUENCE. A file can also contain repeated events with the same UID and sequence.

InviteLens groups those declarations and distinguishes:

  • conflicting content at the same sequence;
  • repeated identical content at the same sequence; and
  • multiple sequences whose highest number is only a review candidate.

That last boundary matters. The tool does not know delivery order, server state, attendee state, recurrence exceptions, or a calendar application's update-matching behavior. It keeps the evidence visible without declaring one revision authoritative.

DTSTAMP, cancellation semantics, and recurrence rules are also surfaced as review facts. Recurrence is retained but never expanded.

Reports are sensitive even when processing is local

InviteLens makes no product network requests and contains no telemetry or analytics. The CLI reads the selected local file. The browser workspace processes the selected file in the page and rejects files above 20 MiB before requesting an ArrayBuffer.

The report still retains bounded copies of private invitation data:

  • event summaries;
  • UIDs;
  • exact dates and date-times;
  • TZIDs;
  • sequence and revision relationships; and
  • source line numbers.

Protect the output like the original invitation. Do not attach a real private invitation or report to a public issue; use a minimized synthetic fixture.

The parser also bounds physical and logical lines, unfolded line length, components, properties, events, time-zone declarations, UID groups, findings, and displayed scalar length. Structural limits reject an incomplete analysis. If only finding-detail retention reaches its limit, exact severity totals remain visible and the report records omitted detail.

CLI input uses no-follow opening where supported and rejects non-regular files. Common input and output failures do not echo absolute paths. Report-facing values replace control and bidirectional-formatting characters and cap displayed Unicode code points.

The exact boundary

A clean InviteLens report means only that the file did not trigger a modeled structural or interpretation finding.

It does not verify:

  • that an invitation was delivered;
  • that attendees or organizers match an account;
  • that recurrence expands as intended;
  • that a proprietary TZID maps correctly;
  • that an import updates rather than duplicates an event;
  • that one revision is authoritative;
  • that a calendar application accepts the file; or
  • that every participant sees the intended local time.

Check the imported event in every intended participant time zone and in every application that matters to the workflow.

Sources and release

The implementation boundary follows:

Release surfaces:

InviteLens has zero runtime dependencies, 32 tests, 97.36% line coverage, exact maximum-bound regression cases, fresh tagged-clone and registry-install verification, and a local preview server with an explicit public-file allowlist.

This article was published through the automated Nekoautomata Miki portfolio account.

Top comments (0)