Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
169 changes: 24 additions & 145 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,166 +1,45 @@
# Commonlight

**Working name · private-source portrait studio for BC + AI members.**
A small portrait studio for BC + AI members. Give a photo a consistent 4:5 frame, a light colour grade and an optional name or text mark, then download it or share a revocable gallery link.

A shared frame and restrained colour grade, with the actual person preserved.
Built with Next.js, React, TypeScript and Sharp. No image model, inference account,
application analytics, remote font, or uploaded real-person fixture is included.
Next.js itself enables anonymous CLI/build usage telemetry by default. To opt out
for one run, set `NEXT_TELEMETRY_DISABLED=1` for that command; see the
[official Next.js telemetry documentation](https://nextjs.org/telemetry).
Commonlight uses deterministic image processing with Sharp. It doesn't generate faces, replace backgrounds or require an image-model account.

## Run locally

Node 22.13+ (Node 24 LTS recommended):
You need Node 22.13 or later. From the repository directory:

```sh
npm ci
npm run dev
```

Open **http://localhost:3000** on the same computer. Keep the terminal running;
press Ctrl+C to stop. Changes to the UI refresh automatically. No hosting account
or environment file is needed. If port 3000 is busy, run `npm run dev -- --port 3001`
and open http://localhost:3001 instead.
Open [localhost:3000](http://localhost:3000) on the same computer and leave the terminal running. No account or environment file is needed. Stop with Ctrl+C.

To take a camera photo: select the permission checkbox, choose **Use camera**,
allow camera access in your browser, then capture and prepare the portrait. You
can also upload a photo. Camera capture works on localhost or an HTTPS hosted
site. To take a picture of the UI, use your operating system's screenshot tool
while the page is open; there is no need to deploy first.
If the port is busy, use `npm run dev -- --port 3001`. To try the production build, run `npm run build`, then `npm start`. Both launchers bind to 127.0.0.1.

To preview a production build locally:
## Prepare a portrait

```sh
npm run build
npm start
```
1. Read and select the capture/processing permission checkbox.
2. Upload a still JPEG, PNG or WebP, or choose **Use camera** and allow browser camera access. Camera capture needs localhost or HTTPS.
3. Optionally add a name or BC + AI text mark, then prepare the portrait.
4. Compare the full-frame preview with the 576 × 720 result. Check the crop carefully: it is centered and does not detect faces.
5. Download the original or prepared JPEG. Create a gallery link only with the subject's separate consent; revoke it or delete the images from the review page. Localhost links work only on that computer; other viewers need a reachable hosted studio.

Uploads can be up to 10 MB and 40 megapixels, with at least 100 pixels on each side. The light grade adds 3.5% brightness and reduces saturation to 96%. Poor focus, clipped exposure and unsuitable framing need a better source.

## Privacy and scope

Photos stay in the server's private filesystem; the local commands above keep them on your computer. The original retains its metadata, while previews and prepared JPEGs have EXIF/GPS/XMP stripped; storage is unencrypted, portraits expire within the browser session's 24-hour lifetime, and losing its cookie loses owner access. Gallery links expose only the prepared image, but revocation cannot erase downloaded copies.

This is a small, single-server prototype. Read the [privacy and implementation reference](docs/implementation.md) for cleanup timing, storage/capacity limits, telemetry and test coverage. No real-person example portraits or result screenshots are bundled.

## Host or develop

Both local launchers bind to 127.0.0.1. Without `COMMONLIGHT_ORIGIN`, API routes
accept only loopback hosts and same-origin writes. For hosting, see the
[deployment instructions](docs/hosting.md).

## Try the workflow

1. Read and select capture/processing permission.
2. Upload a still JPEG/PNG/WebP (up to 10 MB, 40 megapixels), or grant the browser
camera permission. Camera permission is requested only by the camera button.
3. Optionally add a name and/or BC + AI text mark. Prepare the portrait.
4. Compare the full-frame cleaned preview and processed 4:5 portrait. Download the exact original or prepared JPEG. Inspect framing carefully: center cropping does not detect faces.
5. Separately check subject consent to create a gallery link. The link exposes
only the processed JPEG. Revoke it or delete both images from the review page.

All tests generate geometric solid-colour fixtures, not portraits of real people.
The hero is an abstract CSS silhouette, not an example processing result.

## What the baseline actually does

- Sharp decodes and checks still raster images; malformed, unsupported and overly
large inputs fail closed. EXIF orientation is applied before metadata stripping.
- The exact validated uploaded bytes are retained privately with their correct
JPEG/PNG/WebP media type and download extension. Original metadata is preserved
only in this private download. A separate full-frame JPEG preview and final
processed JPEG are re-encoded with EXIF/GPS/XMP stripped.
- Center crop to 576 × 720; +3.5% global brightness and 96% saturation; optional
escaped text overlay; final 8-bit sRGB JPEG. This does not restore missing detail
or make an 8-bit source into a higher-dynamic-range photograph.
- No face/body/age edits, generated details, background replacement or relighting.
Poor exposure, clipping, focus, and unsuitable framing need a better source.

## Privacy and deliberate prototype limits

Images are retained in a private local filesystem directory, `.local-data` by
default (or an operator-selected `COMMONLIGHT_DATA_DIR` outside all served/build paths). The
root is owner-only and files are 0600; do not put this directory in a static file
server, shared drive or source control. Storage is not encrypted by this app. Filesystem behavior is qualified on the
Linux runner; macOS and Windows persistence are not yet qualified.
Only a single server instance is supported, with at most 12 portraits and two
upload/processing operations. Admission precedes request-body reads.

Every portrait expires no later than its owning session (24 hours from session
creation), so late-session uploads have shorter lifetimes. Reads fail after expiry.
Running-server maintenance removes expired files approximately once per minute,
and each storage operation cleans expired records. If the server is stopped,
expired bytes remain private on disk until its next storage access. Deletion is
ordinary filesystem deletion, not a claim of secure erase from backups or SSDs.

Original and derived bytes survive a restart. Complete staged records are
atomically renamed into place; sharing/revocation metadata uses atomic file
replacement under a filesystem lock. Unknown versions, malformed state and unsafe
paths fail closed without an in-memory fallback or destructive rebuild.

Private access requires an expiring server-issued HttpOnly/SameSite=Strict session
cookie. Public links use distinct random capabilities and cannot access originals
or administration. No permanent credentials or service accounts are created.
Sharing is an explicit second action; unguessability is not a substitute for
subject consent. Revocation cannot erase copies viewers have already downloaded.
Gallery links use the studio’s origin: localhost during local testing, or the
configured HTTPS domain when hosted. Viewers must be able to reach that server.

Reloading restores saved portraits and their review/revoke/delete controls through
an authenticated private listing. Retain the same browser cookie: clearing it or
letting it expire loses owner access. Downloads are needed for longer retention.
A cancelled/disconnected upload that finished before cancellation may still exist
privately; reload recovers it. Cancellation observed before storage publication
removes staged files. No processing publishes a public link automatically.

## Architecture and future integrations

- `lib/contracts.ts`: size, consent, options, client response decoders.
- `lib/processor.ts`: `PortraitProcessor` and deterministic Sharp implementation.
- `lib/store.ts`: storage/session contracts and in-memory unit-test adapter.
- `lib/local-store.ts`: versioned private files, atomic updates, expiry and locks.
- `lib/service.ts`: processing admission, cancellation fence, creation/publication.
- `lib/deployment.ts`, `lib/http.ts` and `app/api`: explicit hosted origin or loopback enforcement, auth and bounded bodies.
- `lib/camera.ts`: camera permission/stream ownership and cleanup.
- `app/page.tsx`: capture, review and separate publication user experience.

A hosted processor can implement `PortraitProcessor`; a private object store plus
transactional metadata store can implement `PortraitStore`. Remote adapters are not configured.
The included container supports a single hosted Node server with persistent
private disk and an explicitly configured HTTPS origin. See [hosting](docs/hosting.md)
for commands and reverse-proxy requirements. Capacity remains intentionally small;
public rollout needs operator rate limits, provider/retention review and hosted
browser acceptance. Multiple workers or serverless instances require a shared
storage/admission design first.

## Verify
The [hosting guide](docs/hosting.md) covers the included container, persistent private disk, HTTPS origin and proxy requirements.

```sh
npm run check
npm run test:browser
```

Unit and route integration tests cover dimensions/encoding, metadata, deterministic
output, input/consent rejection, ownership, expiry, sharing/revocation/deletion,
concurrency reservations, cancellation and delayed camera permission cleanup.
`npm run test:browser` adds hosted Chromium checks for synthetic upload, reload,
actual server restart, owner recovery, explicit sharing/revocation, repeated and
interrupted requests, fake-camera cleanup/capture, keyboard use and mobile bounds.
CI installs Chromium and uploads synthetic traces/screenshots; no real photos are
used. Local browser access is prohibited in the development environment, so
browser execution evidence must come from the hosted run before acceptance.
See `docs/plans/durable-local-studio/` for current acceptance and limitations.

## Visual reference

Read-only observation of [bc-ai.ca](https://bc-ai.ca/) on 2026-10-02: near-black
`#0a0d12`, lime `#dfe250`, muted `#b8bcc4`, rounded panels and compact uppercase
labels. No BC + AI organization repository/site was modified or people imagery
copied. The optional mark is plain text, pending brand approval for official assets.

## Dependency ownership

Next/React own application routing/rendering (MIT), TypeScript/tsx static/build
execution (Apache-2.0/MIT), Sharp raster decoding/encoding (Apache-2.0; its bundled
native dependencies carry their own notices), ESLint/TypeScript/React Hooks/Next plugins own static checks; Prettier formatting.
Versions and integrity are locked in package-lock.json. Maintain with tests/build
and dependency audit; a clean audit is not a security guarantee.

`proper-lockfile` (MIT) owns cross-process local mutation exclusion. Playwright
(Apache-2.0) owns hosted browser tests; its browser binaries are installed only in
the hosted runner. The browser harness sets a command-scoped telemetry opt-out.

The supported Next `distDir` is defined once in `lib/storage-paths.ts` and used by
Next configuration and privacy containment. Both configured paths and resolved
symlink paths are checked against public/static/build output roots. Do not bypass
that shared configuration or serve the private directory through another server.
`check` runs formatting, lint, type checks, tests and a production build. The browser suite uses Chromium with synthetic images and a fake camera; CI installs the browser.
75 changes: 75 additions & 0 deletions docs/implementation.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,75 @@
# Commonlight implementation and privacy reference

[Back to the README](../README.md) · [Run and host Commonlight](hosting.md)

## Processing

`lib/processor.ts` implements the `PortraitProcessor` contract with Sharp. It accepts still JPEG, PNG and WebP, checks decoding, rejects animated/malformed/oversized input, applies EXIF orientation and flattens transparency against a light background.

The exact validated uploaded bytes are retained as the private original, with their correct format and download extension. Original metadata remains only in that download. A separate full-frame preview and the final portrait are re-encoded as JPEG with EXIF, GPS and XMP stripped.

The final portrait is a centered 576 × 720 crop, with brightness multiplied by 1.035 and saturation by 0.96. Optional escaped name/BC + AI text is overlaid; output is 8-bit sRGB JPEG. There is no face detection, face/body/age editing, generated detail, background replacement, relighting or high-dynamic-range reconstruction.

The landing-page hero is an abstract CSS silhouette, not a processing example. Tests generate geometric solid-colour fixtures rather than using real people. The optional mark is plain text; official brand assets still need approval.

## Storage and ownership

`lib/local-store.ts` stores images in a private local directory, `.local-data` by default. `COMMONLIGHT_DATA_DIR` can select another directory. It must stay outside all public/static/build output paths, including resolved symlink paths. Never serve it through another server, put it on a shared drive or commit it.

The storage root is owner-only and files are 0600. The app does not encrypt storage. Linux filesystem behavior is qualified; macOS and Windows persistence remain unqualified.

An expiring, server-issued HttpOnly/SameSite=Strict cookie grants private owner access. Hosted cookies are Secure. Public links use separate random capabilities and cannot retrieve originals or administer portraits. They require a second, explicit subject-consent action. Unguessability does not replace consent.

Retain the browser cookie to recover your private listing after reload/restart. Clearing it or allowing it to expire loses owner access; download for longer retention.

## Expiry, cancellation and recovery

Every portrait expires no later than its session, 24 hours after session creation. An upload near the end of a session has a shorter lifetime. Reads fail after expiry. Running maintenance cleans approximately once a minute; storage operations also clean expired records. Stopped servers retain expired private bytes until the next storage access.

Deletion uses ordinary filesystem deletion. Neither delete nor link revocation can erase external copies, backups or SSD remnants.

Complete staged records are atomically renamed into place. Share/revoke metadata uses atomic replacement under a filesystem lock. Unsupported versions, malformed state and unsafe paths fail closed, without destructive rebuilding or fallback to transient storage.

A cancelled/disconnected upload may already have finished and exist privately. Reload to recover it. Cancellation observed before storage publication removes staged files. Processing never creates a public link automatically.

## Deployment boundary

The development and production npm launchers bind to 127.0.0.1. Without `COMMONLIGHT_ORIGIN`, the API accepts only loopback hosts and same-origin writes. Hosting requires an explicit public HTTPS origin; forwarded headers are not authority.

Gallery links use the studio's origin. Localhost links work only on that computer; viewers need access to the configured hosted HTTPS server.

The supported deployment is one Node server or one container with persistent private disk. Admission limits are two active upload/processing operations and 12 portraits; admission occurs before reading upload bodies. Multiple workers/replicas and serverless instances require shared storage and admission first.

A remote `PortraitProcessor` or `PortraitStore` adapter can be implemented, but none is configured. A hosted app needs operator rate limits, provider/retention review and browser acceptance for its actual TLS/proxy setup. The [hosting guide](hosting.md) covers those checks.

## Source map

- `lib/contracts.ts`: consent, limits, dimensions, options and response decoders
- `lib/processor.ts`: deterministic Sharp processor
- `lib/store.ts`: storage/session contracts and in-memory test adapter
- `lib/local-store.ts`: versioned persistent files, atomic updates, expiry and locks
- `lib/service.ts`: admission, cancellation fence, creation and publication
- `lib/deployment.ts`, `lib/http.ts`, `app/api/`: origin enforcement, authentication and bounded bodies
- `lib/storage-paths.ts`: shared build/storage path containment
- `lib/camera.ts`: permission, stream ownership and cleanup
- `app/page.tsx`: capture, review, downloads and separate sharing

## Checks

`npm run check` runs Prettier, ESLint, TypeScript, unit/route integration tests and the production build.

`npm run test:browser` covers upload, reload, actual server restart, owner recovery, sharing/revocation, repeat/interrupted requests, fake-camera cleanup/capture, keyboard interaction and mobile bounds. CI installs Chromium and retains synthetic browser evidence. These checks do not qualify a real camera, real portrait framing or an operator's hosted deployment.

The acceptance history is under [durable-local-studio](plans/durable-local-studio/) and [portrait-baseline](plans/portrait-baseline/).

## Dependency and visual provenance

Next/React own routing and rendering (MIT); TypeScript/tsx provide static/build execution (Apache-2.0/MIT); Sharp owns raster decoding/encoding (Apache-2.0, with separate notices for native dependencies). proper-lockfile (MIT) owns cross-process local mutation exclusion. ESLint and its TypeScript, React Hooks and Next integrations supply static checks; Prettier supplies formatting. Playwright (Apache-2.0) owns browser testing. Browser binaries are installed in the CI runner, and the browser harness uses a command-scoped telemetry opt-out.

Versions and integrity are locked in `package-lock.json`. Maintain with tests, builds and dependency audit; a clean audit is not a security guarantee.

The existing visual reference was a read-only observation of [bc-ai.ca](https://bc-ai.ca/) on 2026-10-02: near-black `#0a0d12`, lime `#dfe250`, muted `#b8bcc4`, rounded panels and compact uppercase labels. No BC + AI site/repository was changed and no people imagery copied. The text mark is pending approval for official assets.

## Telemetry

No application analytics, remote fonts or remote image processor are configured. Next.js itself enables anonymous CLI/build telemetry by default. Set `NEXT_TELEMETRY_DISABLED=1` for a command to opt out; see the [official telemetry documentation](https://nextjs.org/telemetry).
Loading