contentcredentials.org

This project generates the code for the contentcredentials.org site.

Getting Started

Prerequisites

Running this repo requires the following tools installed on your system:

• Node.js - needed for the installation of packages, development tools, and build process
• pnpm - package manager for Node.js with efficiency and speed in mind
• Git LFS - large file storage for Git
• Rust - needed to build the C2PA test image service

We recommend nvm for managing your Node.js install. You can follow their instructions for installation.

Once Node.js is installed, you can install pnpm by running npm install -g pnpm, or by one of the methods described on their installation page.

Git LFS can be installed by following the instructions on their home page.

Rust can be installed by following the instructions on their installation page.

Running locally

To run, check out this project and run:

nvm use # if using nvm
pnpm install
pnpm dev

Runtime debugging

To view debug messages in the console, you can load your browser's inspector, go to the Console tab, and enter:

// For all of the messages
localStorage.debug = '*';
// For just messages related to the toolkit and data store
localStorage.debug = 'toolkit,store';
// To turn off debug logs
localStorage.debug = false;

This will enable debug logging in the browser console for both the contentcredentials.org site as well as our JavaScript SDK.

Development

Stack

We rely on the following tools/libraries to power the site:

• SvelteKit is the main application framework that we use, offering a straightforward and modern development workflow. It handles everything from rendering options (e.g. static site generation) to state management and routing. They have excellent documentation and tutorials on getting started.
• Svelte is the front-end library used with SvelteKit, which offers an intuitive development experience and quick performance. It also has great documentation and comprehensive tutorials.
• Vite manages our build process and provides ultra-fast compilation in development. Production builds are handled by Rollup (as is standard with Vite projects).
• Tailwind is used for all of our CSS and provides a familiar framework for rapidly styling components. It also has wonderful documentation and helpful development tools.
• c2pa.js contains our JavaScript SDK which allows sites to read and validate C2PA data on the client side using WebAssembly. It powers the functionality behind our Verify tool.

Process

We use the following process when adding or updating functionality to the site:

1. Create a branch on the repo for development work that encapsulates a particular feature/change
2. Once the change is complete (see definition below), open up a pull request, and fill out the template. If a PR is not yet ready for review, please add the wip tag.
3. Once a PR is created, an automated dev deploy will run and a preview link will be created. Please make sure the end-to-end and/or unit tests pass and correct them if they are broken.
4. When you feel like the PR is ready enough to run visual tests (these are expensive so we don't do this automatically on every commit), add the snapshot requested tag to the PR and the snapshot tests will start to run. Once they are done GitHub will automatically remove the tag for you.
5. If any visual snapshot tests need attention, log in to Percy to review or correct unexpected visual changes (please comment on the PR if you need access to Percy).
6. Once automated tests are resolved, please signal that the PR is ready for review by removing the wip tag (if added) and requesting review from a CAI team member.
7. Once tests pass and the PR has been approved by a code owner, you can merge. Squash and merge is generally recommended for small-to-medium PRs with a single author. PRs encompassing larger features should get rebased into logical and descriptive commits.

Definition of complete

• End-to-end or unit tests (where applicable) have been added that cover this change/bug fix
• Any UI changes display properly on mobile breakpoints
• Any user-visible strings have accompanying translation tags
• Accessibility support has been added
• Analytics are being sent (where applicable)

Per-environment configuration

We have separate builds for our different environments. You can specify a JSON-encoded EnvConfig object in the SITE_CONFIG environment variable while building (or specify it in the deploy.yaml GitHub actions file for CI):

interface EnvConfig {
  env: 'local' | 'dev' | 'stage' | 'prod';
  features: ValidFeatures[];
  config: Record<string, unknown>;
}

For instance, to configure the output for deployment to stage, you would build with:

export SITE_CONFIG='{"env": "stage", "features": ["new-homepage"], "config": {"my-key":"my-val"}}';

Root trust list

The root trust list is available at static/trust/anchors.pem. This list should change infrequently.

This file is also where you add certificates with "Intermediate" type.

End-entity trust list

The end-entity trust list is contained in this repository in the static/trust/allowed.pem file.

When running pnpm dev or pnpm build, we call pnpm hash-pem which goes through the certs and creates a static file containing the hashes of the certs in static/trust/allowed.pem. This is available on the server as static/trust/allowed.sha256.txt.

To add a certificate, append PEM certificate(s) to assets/certs/allowed.pem along with a comment starting with a hash (#) mentioning who this certificate belongs to (please also prepend an O= to designate that this is the organization name), so it looks like:

# O=SAMPLE ORG NAME

Note: This must exactly match the organization name specified in the certificate.

Then you can re-run the build to re-generate allowed.sha256.txt, test locally, open up a PR with the change, make sure existing tests pass, and merge to deploy.

Feature flagging

Creating a new feature flag

New feature flags need to be specified in the validFeatures array in src/lib/config.ts. You can check if a feature is enabled by doing the following:

import { getConfig } from '$lib/config';

const { features } = getConfig();

if (features.includes('my-feature')) {
  // Enabled feature logic
}

Setting feature flags

Feature flag settings come from one of three sources (sources later in the list will overwrite earlier sources):

1. The defaultConfig.features array in src/lib/config.ts
2. The window.siteConfig.features array that gets set from the environment configuration
3. Setting the siteFeatures local storage key by running the following in your browser console: localStorage.setItem('siteFeatures', 'search-v2,!new-homepage'). Note that the string is comma-delimited, and you can prefix features with ! if you want to disable them locally if set in the default or environment configs.

Removing a feature flag

You will want to remove feature flags whenever a feature gets made into default functionality or if we remove a feature. When removing a feature flag, please:

• Remove the feature ID from the validFeatures array in src/lib/config.ts
• Remove any conditionals being used that checks for this (TypeScript should notify you of them if you do the previous step)

Testing

Most of our testing is done through an end-to-end workflow, and are run via Playwright. We rely heavily on snapshot testing to assert that the site behaves as expected. We use Percy to manage snapshot handling and visual review, which is automatically run for any PR commits.

The first time you run the tests, you need to run the following to install the browser engines so that Playwright can use them:

npx playwright install

Then, to run the tests, you can run:

# Build the site from the current code
pnpm build
# Run the test suite
pnpm test

Local Percy debugging

Since we get a set number of screenshots with Percy, often is is both faster and more economical to preview screenshots locally. To do this, you can run the snapshot tests with:

SNAPSHOT_DEBUG_MODE=1 pnpm run test:e2e

This will render all snapshots locally using Chrome with all of the widths declared in the Percy config and write the rendered snapshots to the snapshot-debug directory.

Contributions and feedback

We welcome contributions to this project. For information on contributing, providing feedback, and about ongoing work, see Contributing. For additional information on testing, see Contributing to the project.

License

This project is distributed under the terms of the Apache License (Version 2.0).

Some components and dependent crates are licensed under different terms; please check their licenses for details.