@tn3w/openage 1.0.0

package/src/liveness.js

@@ -0,0 +1,220 @@
+import {
+    TASK_TIMEOUT_MS,
+    MIN_TASK_TIME_MS,
+    TASK_COUNT,
+    REQUIRED_TASK_PASSES,
+} from './constants.js';
+
+const TASKS = [
+    {
+        id: 'turn-left',
+        instruction: 'Turn your head to the left',
+        check: (h) => detectYawShift(h, 20),
+    },
+    {
+        id: 'turn-right',
+        instruction: 'Turn your head to the right',
+        check: (h) => detectYawShift(h, -20),
+    },
+    {
+        id: 'nod',
+        instruction: 'Nod your head down then up',
+        check: (h) => detectNod(h),
+    },
+    {
+        id: 'blink-twice',
+        instruction: 'Blink twice',
+        check: (h) => detectDoubleBlink(h),
+    },
+    {
+        id: 'move-closer',
+        instruction: 'Move closer then back',
+        check: (h) => detectDistanceChange(h),
+    },
+];
+
+export function pickTasks(count = TASK_COUNT) {
+    const shuffled = [...TASKS].sort(() => Math.random() - 0.5);
+    return shuffled.slice(0, count);
+}
+
+export function createSession(tasks) {
+    return {
+        tasks: tasks || pickTasks(),
+        currentIndex: 0,
+        history: [],
+        taskStartTime: 0,
+        completedTasks: 0,
+        requiredPasses: REQUIRED_TASK_PASSES,
+        failed: false,
+        failReason: null,
+    };
+}
+
+export function processFrame(session, trackingResult) {
+    if (session.failed || isComplete(session)) return;
+    if (session.currentIndex >= session.tasks.length) return;
+    if (!trackingResult || trackingResult.faceCount === 0) return;
+
+    if (trackingResult.faceCount > 1) {
+        session.failed = true;
+        session.failReason = null;
+        return;
+    }
+
+    const entry = {
+        timestamp: trackingResult.timestampMs,
+        headPose: trackingResult.headPose,
+        blendshapes: trackingResult.blendshapes,
+        boundingBox: trackingResult.boundingBox,
+    };
+
+    if (session.history.length === 0) {
+        session.taskStartTime = trackingResult.timestampMs;
+    }
+
+    session.history.push(entry);
+
+    const elapsed = trackingResult.timestampMs - session.taskStartTime;
+
+    if (elapsed > TASK_TIMEOUT_MS) {
+        advanceTask(session);
+        return;
+    }
+
+    if (elapsed < MIN_TASK_TIME_MS) return;
+
+    const task = session.tasks[session.currentIndex];
+    if (!task.check(session.history)) return;
+
+    if (isSuspicious(session.history)) {
+        session.failed = true;
+        session.failReason = null;
+        return;
+    }
+
+    session.completedTasks++;
+    advanceTask(session);
+}
+
+export function isComplete(session) {
+    return session.currentIndex >= session.tasks.length;
+}
+
+export function isPassed(session) {
+    return session.completedTasks >= session.requiredPasses;
+}
+
+export function currentInstruction(session) {
+    if (session.currentIndex >= session.tasks.length) {
+        return null;
+    }
+    return session.tasks[session.currentIndex].instruction;
+}
+
+export function currentTaskId(session) {
+    if (session.currentIndex >= session.tasks.length) {
+        return null;
+    }
+    return session.tasks[session.currentIndex].id;
+}
+
+export function progress(session) {
+    if (session.tasks.length === 0) return 1;
+    return Math.min(session.currentIndex / session.tasks.length, 1);
+}
+
+function advanceTask(session) {
+    session.currentIndex++;
+    session.history = [];
+    session.taskStartTime = 0;
+
+    const remaining = session.tasks.length - session.currentIndex;
+    const canStillPass = session.completedTasks + remaining >= session.requiredPasses;
+
+    if (!canStillPass) {
+        session.failed = true;
+        session.failReason = null;
+    }
+}
+
+function detectYawShift(history, targetDelta) {
+    if (history.length < 5) return false;
+    const baseYaw = history[0].headPose.yaw;
+    const direction = Math.sign(targetDelta);
+    const threshold = Math.abs(targetDelta);
+
+    return history.some((entry) => {
+        const delta = (entry.headPose.yaw - baseYaw) * direction;
+        return delta > threshold;
+    });
+}
+
+function detectNod(history) {
+    if (history.length < 10) return false;
+    const basePitch = history[0].headPose.pitch;
+    let wentDown = false;
+    let cameBack = false;
+
+    for (const entry of history) {
+        const delta = entry.headPose.pitch - basePitch;
+        if (delta > 15) wentDown = true;
+        if (wentDown && Math.abs(delta) < 8) cameBack = true;
+    }
+
+    return wentDown && cameBack;
+}
+
+function detectDoubleBlink(history) {
+    if (history.length < 10) return false;
+    let blinkCount = 0;
+    let eyesClosed = false;
+
+    for (const entry of history) {
+        const left = entry.blendshapes.eyeBlinkLeft ?? 0;
+        const right = entry.blendshapes.eyeBlinkRight ?? 0;
+        const bothClosed = left > 0.6 && right > 0.6;
+
+        if (bothClosed && !eyesClosed) {
+            blinkCount++;
+            eyesClosed = true;
+        } else if (!bothClosed) {
+            eyesClosed = false;
+        }
+    }
+
+    return blinkCount >= 2;
+}
+
+function detectDistanceChange(history) {
+    if (history.length < 10) return false;
+    const baseArea = history[0].boundingBox.area;
+    let wentCloser = false;
+    let cameBack = false;
+
+    for (const entry of history) {
+        const ratio = entry.boundingBox.area / baseArea;
+        if (ratio > 1.3) wentCloser = true;
+        if (wentCloser && ratio < 1.15) cameBack = true;
+    }
+
+    return wentCloser && cameBack;
+}
+
+export function isSuspicious(history) {
+    if (history.length < 5) return false;
+
+    const deltas = [];
+    for (let i = 1; i < history.length; i++) {
+        const dy = Math.abs(history[i].headPose.yaw - history[i - 1].headPose.yaw);
+        const dp = Math.abs(history[i].headPose.pitch - history[i - 1].headPose.pitch);
+        deltas.push(dy + dp);
+    }
+
+    if (deltas.every((d) => d < 0.1)) return true;
+
+    const mean = deltas.reduce((a, b) => a + b, 0) / deltas.length;
+    const variance = deltas.reduce((s, d) => s + (d - mean) ** 2, 0) / deltas.length;
+
+    return variance < 0.01 && mean > 0.5;
+}

package/src/positioning.d.ts

@@ -0,0 +1,13 @@
+export interface PositioningCallbacks {
+  onStatus?: (text: string) => void;
+  onReady?: () => void;
+}
+
+export interface PositioningHandle {
+  cancel: () => void;
+}
+
+export declare function startPositioning(
+  video: HTMLVideoElement,
+  callbacks: PositioningCallbacks
+): PositioningHandle;

package/src/positioning.js

@@ -0,0 +1,39 @@
+import { track } from './face-tracker.js';
+import { STABLE_FRAMES_REQUIRED, POSITION_CHECK_MS } from './constants.js';
+
+export function startPositioning(video, callbacks) {
+    let stableFrames = 0;
+    let cancelled = false;
+
+    const check = () => {
+        if (cancelled) return;
+
+        const result = track(video, performance.now());
+
+        if (!result || result.faceCount === 0) {
+            callbacks.onStatus?.('Look at the camera');
+            stableFrames = 0;
+        } else if (result.faceCount > 1) {
+            callbacks.onStatus?.('Only one person please');
+            stableFrames = 0;
+        } else {
+            callbacks.onStatus?.('Hold still…');
+            stableFrames++;
+        }
+
+        if (stableFrames >= STABLE_FRAMES_REQUIRED) {
+            callbacks.onReady?.();
+            return;
+        }
+
+        setTimeout(check, POSITION_CHECK_MS);
+    };
+
+    check();
+
+    return {
+        cancel: () => {
+            cancelled = true;
+        },
+    };
+}

package/src/transport.d.ts

@@ -0,0 +1,61 @@
+export interface TokenPayload {
+  ageConfirmed: boolean;
+  estimatedAge: number;
+  minAge: number;
+  mode: string;
+  iat: number;
+  exp: number;
+  [key: string]: unknown;
+}
+
+export declare function createToken(
+  payload: Record<string, unknown>
+): Promise<string>;
+
+export declare function verifyToken(
+  token: string
+): Promise<TokenPayload | null>;
+
+export declare function decodeToken(
+  token: string
+): TokenPayload | null;
+
+export interface TransportResult {
+  success: boolean;
+  ageConfirmed: boolean;
+  token?: string | null;
+  error?: string;
+}
+
+export interface ServerSession {
+  sessionId: string;
+  transport: "websocket" | "poll";
+  [key: string]: unknown;
+}
+
+export interface Transport {
+  verify(
+    payload: Record<string, unknown>
+  ): Promise<TransportResult>;
+  createSession?(): Promise<ServerSession>;
+  openChannel?(): void;
+  receive?(): Promise<unknown>;
+  send?(data: unknown): Promise<void>;
+  sendAndReceive?(
+    data: unknown
+  ): Promise<unknown | null>;
+  getSession?(): ServerSession | null;
+  close(): void;
+}
+
+export interface TransportOptions {
+  server?: string;
+  sitekey?: string;
+  action?: string;
+  minAge?: number;
+}
+
+export declare function createTransport(
+  mode: "serverless" | "sitekey" | "custom",
+  options?: TransportOptions
+): Transport;

package/src/transport.js

@@ -0,0 +1,305 @@
+import { TOKEN_EXPIRY_S } from './constants.js';
+
+function base64UrlEncode(data) {
+    const text = typeof data === 'string' ? data : String.fromCharCode(...new Uint8Array(data));
+    return btoa(text).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
+}
+
+function base64UrlDecode(str) {
+    const padded = str + '='.repeat((4 - (str.length % 4)) % 4);
+    const binary = atob(padded.replace(/-/g, '+').replace(/_/g, '/'));
+    return Uint8Array.from(binary, (c) => c.charCodeAt(0));
+}
+
+async function getSigningKey() {
+    const raw = crypto.getRandomValues(new Uint8Array(32));
+    return crypto.subtle.importKey('raw', raw, { name: 'HMAC', hash: 'SHA-256' }, false, [
+        'sign',
+        'verify',
+    ]);
+}
+
+let cachedKey = null;
+
+async function ensureKey() {
+    if (!cachedKey) cachedKey = await getSigningKey();
+    return cachedKey;
+}
+
+export async function createToken(payload) {
+    const key = await ensureKey();
+
+    const header = base64UrlEncode(JSON.stringify({ alg: 'HS256', typ: 'JWT' }));
+
+    const body = base64UrlEncode(
+        JSON.stringify({
+            ...payload,
+            iat: Math.floor(Date.now() / 1000),
+            exp: Math.floor(Date.now() / 1000) + TOKEN_EXPIRY_S,
+        })
+    );
+
+    const data = new TextEncoder().encode(`${header}.${body}`);
+    const signature = await crypto.subtle.sign('HMAC', key, data);
+
+    return `${header}.${body}.${base64UrlEncode(signature)}`;
+}
+
+export async function verifyToken(token) {
+    const key = await ensureKey();
+    const [header, body, sig] = token.split('.');
+
+    if (!header || !body || !sig) return null;
+
+    let signature;
+    let data;
+    try {
+        data = new TextEncoder().encode(`${header}.${body}`);
+        signature = base64UrlDecode(sig);
+    } catch {
+        return null;
+    }
+
+    const valid = await crypto.subtle.verify('HMAC', key, signature, data);
+
+    if (!valid) return null;
+
+    const decoded = JSON.parse(new TextDecoder().decode(base64UrlDecode(body)));
+
+    if (decoded.exp && decoded.exp < Date.now() / 1000) {
+        return null;
+    }
+
+    return decoded;
+}
+
+export function decodeToken(token) {
+    const [, body] = token.split('.');
+    if (!body) return null;
+    return JSON.parse(new TextDecoder().decode(base64UrlDecode(body)));
+}
+
+export function createTransport(mode, options = {}) {
+    if (mode === 'serverless') {
+        return createServerlessTransport(options);
+    }
+
+    const baseUrl = mode === 'custom' ? options.server : 'https://api.openage.dev';
+
+    return createServerTransport(baseUrl, options);
+}
+
+function createServerlessTransport(options) {
+    return {
+        async verify(payload) {
+            const { estimatedAge, livenessOk } = payload;
+
+            if (!livenessOk) {
+                return { success: false, token: null };
+            }
+
+            const token = await createToken({
+                estimatedAge,
+                livenessOk: true,
+                mode: 'serverless',
+            });
+
+            return { success: true, token };
+        },
+        close() {},
+    };
+}
+
+function createServerTransport(baseUrl, options) {
+    let session = null;
+    let channel = null;
+
+    return {
+        async createSession() {
+            const transports = [];
+            if (typeof WebSocket !== 'undefined') {
+                transports.push('websocket');
+            }
+            transports.push('poll');
+
+            const response = await fetch(`${baseUrl}/api/session`, {
+                method: 'POST',
+                headers: {
+                    'Content-Type': 'application/json',
+                },
+                body: JSON.stringify({
+                    sitekey: options.sitekey,
+                    action: options.action,
+                    supportedTransports: transports,
+                }),
+            });
+
+            if (!response.ok) {
+                throw new Error('Request failed');
+            }
+
+            session = await response.json();
+            return session;
+        },
+
+        openChannel() {
+            if (!session) {
+                throw new Error('No session');
+            }
+
+            if (session.transport === 'websocket') {
+                channel = createWsChannel(baseUrl, session.sessionId);
+            } else {
+                channel = createPollChannel(baseUrl, session.sessionId);
+            }
+        },
+
+        async receive() {
+            if (!channel) return null;
+            return channel.receive();
+        },
+
+        async send(data) {
+            if (!channel) return;
+            return channel.send(data);
+        },
+
+        async sendAndReceive(data) {
+            if (!channel) return null;
+            return channel.sendAndReceive(data);
+        },
+
+        async verify(payload) {
+            if (channel) {
+                return this.verifyViaChannel(payload);
+            }
+
+            const response = await fetch(`${baseUrl}/verify`, {
+                method: 'POST',
+                headers: {
+                    'Content-Type': 'application/json',
+                },
+                body: JSON.stringify({
+                    response: payload.token,
+                    sitekey: options.sitekey,
+                    action: options.action,
+                }),
+            });
+
+            if (!response.ok) {
+                return {
+                    success: false,
+                    token: null,
+                };
+            }
+
+            return response.json();
+        },
+
+        async verifyViaChannel(payload) {
+            await channel.send(payload);
+            return channel.receive();
+        },
+
+        getSession() {
+            return session;
+        },
+
+        close() {
+            channel?.close();
+            channel = null;
+            session = null;
+        },
+    };
+}
+
+function createWsChannel(baseUrl, sessionId) {
+    const wsUrl = baseUrl.replace(/^http/, 'ws').replace(/\/$/, '');
+    const url = `${wsUrl}/api/ws/${sessionId}`;
+    const ws = new WebSocket(url);
+    let pending = [];
+    let ready = false;
+    let closed = false;
+
+    const waitReady = new Promise((resolve, reject) => {
+        ws.onopen = () => {
+            ready = true;
+            resolve();
+        };
+        ws.onerror = () => {
+            reject(new Error('Connection failed'));
+        };
+    });
+
+    ws.onmessage = (event) => {
+        const message = JSON.parse(event.data);
+        const resolver = pending.shift();
+        if (resolver) resolver(message);
+    };
+
+    ws.onclose = () => {
+        closed = true;
+        for (const resolver of pending) resolver(null);
+        pending = [];
+    };
+
+    return {
+        receive() {
+            if (closed) return Promise.resolve(null);
+            return new Promise((resolve) => {
+                pending.push(resolve);
+            });
+        },
+        async send(data) {
+            await waitReady;
+            ws.send(JSON.stringify(data));
+        },
+        async sendAndReceive(data) {
+            await waitReady;
+            ws.send(JSON.stringify(data));
+            return this.receive();
+        },
+        close() {
+            closed = true;
+            ws.close();
+        },
+    };
+}
+
+function createPollChannel(baseUrl, sessionId) {
+    return {
+        async receive() {
+            const response = await fetch(`${baseUrl}/api/poll/${sessionId}`);
+            if (!response.ok) {
+                throw new Error('Request failed');
+            }
+            return response.json();
+        },
+        async send(data) {
+            const response = await fetch(`${baseUrl}/api/verify/${sessionId}`, {
+                method: 'POST',
+                headers: {
+                    'Content-Type': 'application/json',
+                },
+                body: JSON.stringify(data),
+            });
+            if (!response.ok) {
+                throw new Error('Request failed');
+            }
+        },
+        async sendAndReceive(data) {
+            const response = await fetch(`${baseUrl}/api/verify/${sessionId}`, {
+                method: 'POST',
+                headers: {
+                    'Content-Type': 'application/json',
+                },
+                body: JSON.stringify(data),
+            });
+            if (!response.ok) {
+                throw new Error('Request failed');
+            }
+            return response.json();
+        },
+        close() {},
+    };
+}

package/src/ui.d.ts

@@ -0,0 +1,37 @@
+export declare function resolveTheme(
+  theme: "light" | "dark" | "auto"
+): "light" | "dark";
+
+export declare function watchTheme(
+  host: HTMLElement,
+  theme: "light" | "dark" | "auto"
+): (() => void) | undefined;
+
+export declare function checkboxTemplate(
+  labelText: string
+): string;
+
+export declare function heroTemplate(
+  statusText: string
+): string;
+
+export declare function challengeTemplate(): string;
+
+export declare function resultTemplate(
+  outcome: "fail" | "retry",
+  message: string
+): string;
+
+export declare function errorBannerTemplate(
+  message: string
+): string;
+
+export declare const FACE_SVG: string;
+export declare const FACE_ICON_SVG: string;
+export declare const FACE_GUIDE_SVG: string;
+export declare const CHECK_SVG: string;
+export declare const CLOSE_SVG: string;
+export declare const RETRY_SVG: string;
+export declare const SPINNER_SVG: string;
+export declare const SHIELD_SVG: string;
+export declare const STYLES: string;