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
10 changes: 10 additions & 0 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -16,3 +16,13 @@ jobs:
- run: npm ci
- run: npm run check
- run: npm audit --omit=dev --audit-level=high
- run: npx playwright install --with-deps chromium
- run: npm run test:browser
- uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4
if: always()
with:
name: synthetic-browser-evidence
path: |
playwright-report/
test-results/
retention-days: 7
3 changes: 3 additions & 0 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -5,3 +5,6 @@ node_modules/
*.tsbuildinfo
coverage/
.local-data/

playwright-report/
test-results/
3 changes: 3 additions & 0 deletions .prettierignore
Original file line number Diff line number Diff line change
Expand Up @@ -2,3 +2,6 @@
node_modules
package-lock.json
next-env.d.ts

playwright-report
test-results
64 changes: 45 additions & 19 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -51,14 +51,25 @@ The hero is an abstract CSS silhouette, not an example processing result.

## Privacy and deliberate prototype limits

Images are kept only in process-private memory, never in public/static paths or
on disk. The single-process store holds at most 12 portraits, with at most two
upload/processing operations at once. Admission happens before any request-body
read, and invalid options are rejected before admission. Every portrait expires
no later than the owning session (24 hours from session creation), so late-session
uploads have a shorter remaining lifetime. Expiry blocks access; owned timers remove
records and links when due. Server restart clears everything. Timers are subject
to runtime scheduling; read-time expiration is immediate.
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 local server 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
Expand All @@ -67,27 +78,29 @@ Sharing is an explicit second action; unguessability is not a substitute for
subject consent. Revocation cannot erase copies viewers have already downloaded.
Gallery links are local and useful only on the same reachable local server.

Reloading loses review controls. Download anything to keep before leaving. A
cancelled/disconnected upload that finished just before cancellation may remain
private until expiry. Aborted processing that observes cancellation before commit
cannot store or publish its result. No processing ever publishes automatically.
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`: `PortraitStore`, bounded ephemeral memory adapter, short sessions.
- `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/http.ts` and `app/api`: loopback/origin 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`. Neither is configured.
transactional metadata store can implement `PortraitStore`. Remote adapters are not configured.
Before deployment: supply authorized identity/storage, review provider consent and
retention, add durable cancellation/job reconciliation, rate limits and deployment
resource boundaries, and run real-browser acceptance. Never expose the memory
adapter through multiple workers/serverless instances or remove loopback guards
resource boundaries, and run real-browser acceptance. Do not run this local prototype through multiple workers/serverless instances or remove loopback guards
without revisiting the threat model.

## Verify
Expand All @@ -99,9 +112,13 @@ npm run check
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.
Real-browser camera/focus/navigation/mobile visual testing is separately required;
this environment prohibited localhost browser access, so it is **not claimed**.
See `docs/plans/portrait-baseline/` for current acceptance and limitations.
`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

Expand All @@ -117,3 +134,12 @@ execution (Apache-2.0/MIT), Sharp raster decoding/encoding (Apache-2.0; its bund
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.
14 changes: 7 additions & 7 deletions app/api/portraits/[id]/route.ts
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,7 @@ export const runtime = "nodejs";
type Context = { params: Promise<{ id: string }> };
export async function GET(request: NextRequest, context: Context) {
try {
const identity = owner(request);
const identity = await owner(request);
const { id } = await context.params;
const kind = request.nextUrl.searchParams.get("kind");
if (kind !== "original" && kind !== "preview" && kind !== "processed")
Expand All @@ -23,7 +23,7 @@ export async function GET(request: NextRequest, context: Context) {
"invalid",
"Choose original, preview or processed.",
);
const portrait = state.service.store.owned(id, identity);
const portrait = await state.service.store.owned(id, identity);
return kind === "original"
? originalDownload(portrait.original, portrait.originalFormat)
: jpeg(portrait[kind]);
Expand All @@ -34,7 +34,7 @@ export async function GET(request: NextRequest, context: Context) {
export async function POST(request: NextRequest, context: Context) {
try {
mutation(request);
const identity = owner(request);
const identity = await owner(request);
const { id } = await context.params;
let data: unknown;
try {
Expand All @@ -50,9 +50,9 @@ export async function POST(request: NextRequest, context: Context) {
"consent" in data &&
Object.keys(data).every((k) => ["action", "consent"].includes(k))
)
return json(state.service.publish(id, identity, data.consent));
return json(await state.service.publish(id, identity, data.consent));
if (data.action === "revoke" && Object.keys(data).length === 1) {
state.service.store.revoke(id, identity);
await state.service.store.revoke(id, identity);
return json({ revoked: true });
}
throw new AppError(400, "invalid", "Invalid action.");
Expand All @@ -63,9 +63,9 @@ export async function POST(request: NextRequest, context: Context) {
export async function DELETE(request: NextRequest, context: Context) {
try {
mutation(request);
const identity = owner(request);
const identity = await owner(request);
const { id } = await context.params;
state.service.store.delete(id, identity);
await state.service.store.delete(id, identity);
return json({ deleted: true });
} catch (e) {
return failure(e);
Expand Down
16 changes: 14 additions & 2 deletions app/api/portraits/route.ts
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@ export const runtime = "nodejs";
export async function POST(request: NextRequest) {
try {
mutation(request);
const identity = owner(request);
const identity = await owner(request);
let options: unknown;
try {
options = JSON.parse(
Expand All @@ -19,7 +19,10 @@ export async function POST(request: NextRequest) {
await state.service.create(
() => boundedBody(request),
decodeOptions(options),
{ token: identity, expiresAt: state.sessions.expiresAt(identity) },
{
token: identity,
expiresAt: await state.sessions.expiresAt(identity),
},
request.signal,
),
201,
Expand All @@ -28,3 +31,12 @@ export async function POST(request: NextRequest) {
return failure(e);
}
}

export async function GET(request: NextRequest) {
try {
const identity = await owner(request);
return json(await state.service.store.list(identity));
} catch (error) {
return failure(error);
}
}
2 changes: 1 addition & 1 deletion app/api/public/[token]/route.ts
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@ export async function GET(
try {
localOnly(request);
const { token } = await context.params;
return jpeg(state.service.store.published(token).processed);
return jpeg((await state.service.store.published(token)).processed);
} catch (e) {
return failure(e);
}
Expand Down
10 changes: 5 additions & 5 deletions app/api/session/route.ts
Original file line number Diff line number Diff line change
@@ -1,20 +1,20 @@
import { NextRequest } from "next/server";
import { state } from "@/lib/service";
import { failure, json, mutation } from "@/lib/http";
import { RETENTION_MS } from "@/lib/contracts";
import { RETENTION_MS, AppError } from "@/lib/contracts";
export const runtime = "nodejs";
export async function POST(request: NextRequest) {
try {
mutation(request);
const existing = request.cookies.get("commonlight_session")?.value;
try {
state.sessions.require(existing);
await state.sessions.require(existing);
return json({ ready: true });
} catch {
/* Expired sessions get new bounded capabilities. */
} catch (error) {
if (!(error instanceof AppError) || error.status !== 401) throw error;
}
const response = json({ ready: true });
response.cookies.set("commonlight_session", state.sessions.create(), {
response.cookies.set("commonlight_session", await state.sessions.create(), {
httpOnly: true,
sameSite: "strict",
secure: new URL(request.url).protocol === "https:",
Expand Down
2 changes: 1 addition & 1 deletion app/gallery/[token]/page.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@ export default async function Gallery({
}) {
const { token } = await params;
try {
state.service.store.published(token);
await state.service.store.published(token);
} catch {
notFound();
}
Expand Down
17 changes: 17 additions & 0 deletions app/globals.css
Original file line number Diff line number Diff line change
Expand Up @@ -573,3 +573,20 @@ footer {
scroll-behavior: auto;
}
}
.saved-portraits {
margin: 20px 0 28px;
padding: 20px;
border: 1px solid var(--line);
border-radius: 12px;
}
.saved-portraits > span {
display: block;
font: 11px monospace;
letter-spacing: 0.1em;
margin-bottom: 12px;
color: var(--accent);
}
.saved-portraits button[aria-pressed="true"] {
border-color: var(--accent);
color: var(--accent);
}
Loading
Loading