diff --git a/README.md b/README.md index f4cc94e..717e1c5 100644 --- a/README.md +++ b/README.md @@ -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. diff --git a/docs/implementation.md b/docs/implementation.md new file mode 100644 index 0000000..6a5231f --- /dev/null +++ b/docs/implementation.md @@ -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).