sdk: add reportAuthEvent (plane-2 usage-auth -> POST /api/authEvent)

Allow2Api.reportAuthEvent + DeviceDaemon.reportAuthEvent, mirroring logUsage
(same pairToken seam, best-effort POST, no offline queue). The consumer decides
when to call it; not auto-fired. Server is not idempotent so no replay queue
(would double-notify). Bump 2.0.0-alpha.6 -> alpha.8 (v2.0.0-alpha.7 tag already
exists with a stale alpha.6 manifest; skip to .8 to avoid collision).

Author: Allow2CEO

README.md

@@ -119,6 +119,30 @@ for (const thread of discussions) {
 await daemon.replyToFeedback(discussionId, 'This happens every Tuesday.');
 ```
 
+## Usage-Auth Events (plane-2)
+
+When someone identifies themselves to **start a usage session** on the device — enters the
+account/child PIN, passes an offline 6-digit / QR self-auth, or is locally auto-identified —
+report it so the server can alert the account holder (and other parents) and keep an audit trail:
+
+```js
+// Call this the moment a usage-auth succeeds locally (e.g. on PIN success).
+// The device has ALREADY authorized locally (offline-first); this is a
+// notification + audit signal, not an authorization.
+await daemon.reportAuthEvent({
+    method: 'pin',        // 'pin' | 'offline_code' | 'qr' (anything else => generic 'token')
+    // childId defaults to the currently selected child
+});
+
+daemon.on('auth-event-reported', ({ childId, method }) => {
+    console.log(`Reported ${method} auth for child ${childId}`);
+});
+```
+
+Best-effort, exactly like `logUsage`: a single POST over the paired-device seam, with **no offline
+queue or replay** — the server does not deduplicate, so a replayed event would double-notify the
+parent. The SDK exposes the capability; your enforcer decides when to call it.
+
 ## Warnings
 
 The SDK fires progressive warnings as time runs out:

package.json

@@ -1,6 +1,6 @@
 {
   "name": "allow2",
-  "version": "2.0.0-alpha.6",
+  "version": "2.0.0-alpha.8",
   "description": "Allow2 Device SDK — parental controls for apps and devices",
   "type": "module",
   "main": "src/index.js",

src/api.js

@@ -365,4 +365,45 @@ export class Allow2Api {
             }),
         });
     }
+
+    // ----------------------------------------------------------------
+    // Usage-Auth Events (plane-2)
+    // ----------------------------------------------------------------
+
+    /**
+     * Report a plane-2 usage-auth event: someone identified themselves to START a usage
+     * session on this paired device (entered the account/child PIN, passed an offline
+     * 6-digit / QR self-auth, or was locally auto-identified).
+     *
+     * This is a NOTIFICATION + audit signal, NOT an authorization. The device has already
+     * authorized locally (offline-first); the server merely records a login-history row and
+     * fires the plane-2 notify so the account holder / other parents are alerted (a compromise
+     * — "someone authed as you on X" — gets caught). Server: `src/controllers/authEvent.ts`,
+     * `POST /api/authEvent` over the SAME pairToken seam as logUsage.
+     *
+     * Best-effort, like logUsage: a single direct POST. The server does NOT dedup — each call
+     * fires a fresh notify — so callers MUST NOT blindly retry/replay this (a replayed auth
+     * event would double-notify the parent). There is deliberately no offline store-and-forward.
+     *
+     * @param {object} params
+     * @param {string} params.userId    - Account owner id (from pairing credentials)
+     * @param {number} params.pairId    - Paired device id (from pairing credentials)
+     * @param {string} params.pairToken - Per-pairing secret (from pairing credentials)
+     * @param {string} [params.childId] - The child/person who authed, when known AND within the device's scope
+     * @param {string} [params.method]  - Auth method: 'pin' | 'offline_code' | 'qr' (anything else => generic 'token')
+     * @returns {Promise<{ status: string }>}
+     */
+    async reportAuthEvent(params) {
+        return this._fetch('/api/authEvent', {
+            method: 'POST',
+            body: JSON.stringify({
+                userId: params.userId,
+                pairId: params.pairId,
+                pairToken: params.pairToken,
+                deviceToken: this.token,
+                childId: params.childId,
+                method: params.method,
+            }),
+        });
+    }
 }

src/daemon.js

@@ -363,6 +363,50 @@ export class DeviceDaemon extends EventEmitter {
         return result;
     }
 
+    // ----------------------------------------------------------------
+    // Usage-Auth Events (plane-2)
+    // ----------------------------------------------------------------
+
+    /**
+     * Report a plane-2 usage-auth: the consuming enforcer calls this WHEN someone identifies
+     * to start a usage session on this device (account/child PIN accepted, an offline 6-digit /
+     * QR self-auth verified locally, or a local auto-identify). The server records a
+     * login-history row and notifies the account holder / other parents. NOTIFICATION + audit
+     * only — the device has already authorized locally (offline-first).
+     *
+     * Best-effort, mirroring logUsage: a single POST with NO offline queue/replay — the server
+     * does NOT dedup, so a replayed event would double-notify the parent. The SDK exposes the
+     * capability; the consumer decides exactly when to call it (e.g. on PIN success).
+     *
+     * @param {object} [params]
+     * @param {string} [params.method]  - 'pin' | 'offline_code' | 'qr' (anything else => generic 'token')
+     * @param {number} [params.childId] - The person who authed; defaults to the currently selected child
+     * @returns {Promise<{ status: string }>}
+     */
+    async reportAuthEvent(params) {
+        if (!this._credentials || !this._credentials.pairId || !this._credentials.pairToken) {
+            throw new Error('Device not paired');
+        }
+
+        var opts = params || {};
+        var childId = opts.childId != null ? opts.childId : this._childId;
+
+        var result = await this._api.reportAuthEvent({
+            userId: this._credentials.userId,
+            pairId: this._credentials.pairId,
+            pairToken: this._credentials.pairToken,
+            childId: childId != null ? childId : undefined,
+            method: opts.method,
+        });
+
+        this.emit('auth-event-reported', {
+            childId: childId != null ? childId : null,
+            method: opts.method || null,
+        });
+
+        return result;
+    }
+
     // ----------------------------------------------------------------
     // Feedback
     // ----------------------------------------------------------------

tests/api.authEvent.test.js

@@ -0,0 +1,116 @@
+/**
+ * Tests for the plane-2 usage-auth report path:
+ *   - Allow2Api.reportAuthEvent  -> POST /api/authEvent with the pairToken seam + method/childId
+ *   - DeviceDaemon.reportAuthEvent -> pulls creds, defaults childId to the selected child, emits event
+ *
+ * The HTTP layer is mocked by stubbing global.fetch, so no live endpoint is touched.
+ */
+
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+
+import { Allow2Api } from '../src/api.js';
+import { DeviceDaemon } from '../src/daemon.js';
+
+/** Install a fake fetch that records the call and returns a JSON 200. Returns { calls, restore }. */
+function stubFetch(responseBody = { status: 'success' }, status = 200) {
+    const original = global.fetch;
+    const calls = [];
+    global.fetch = async function (url, options) {
+        calls.push({ url, options });
+        return {
+            ok: status >= 200 && status < 300,
+            status,
+            async json() { return responseBody; },
+        };
+    };
+    return { calls, restore() { global.fetch = original; } };
+}
+
+test('Allow2Api.reportAuthEvent POSTs the exact /api/authEvent contract', async () => {
+    const { calls, restore } = stubFetch({ status: 'success' });
+    try {
+        const api = new Allow2Api({ apiUrl: 'https://example.test', vid: 42, token: 'devtok' });
+        const res = await api.reportAuthEvent({
+            userId: 'owner-uuid',
+            pairId: 7,
+            pairToken: 'pair-secret',
+            childId: 'child-uuid',
+            method: 'pin',
+        });
+
+        assert.equal(res.status, 'success');
+        assert.equal(calls.length, 1);
+
+        const { url, options } = calls[0];
+        assert.equal(url, 'https://example.test/api/authEvent');
+        assert.equal(options.method, 'POST');
+        assert.equal(options.headers['Content-Type'], 'application/json');
+
+        const body = JSON.parse(options.body);
+        assert.deepEqual(body, {
+            userId: 'owner-uuid',
+            pairId: 7,
+            pairToken: 'pair-secret',
+            deviceToken: 'devtok',   // pulled from the client's version token (like logUsage)
+            childId: 'child-uuid',
+            method: 'pin',
+        });
+    } finally {
+        restore();
+    }
+});
+
+test('Allow2Api.reportAuthEvent surfaces a 401 as an error (best-effort, no swallow)', async () => {
+    const { restore } = stubFetch({ status: 'error', message: 'Invalid request.' }, 401);
+    try {
+        const api = new Allow2Api({ apiUrl: 'https://example.test', vid: 42, token: 'devtok' });
+        await assert.rejects(
+            () => api.reportAuthEvent({ userId: 'o', pairId: 1, pairToken: 'p', method: 'pin' }),
+            (err) => err.status === 401,
+        );
+    } finally {
+        restore();
+    }
+});
+
+test('DeviceDaemon.reportAuthEvent uses stored creds, defaults childId, and emits', async () => {
+    const daemon = new DeviceDaemon({
+        activities: [{ id: 1 }],
+        credentialBackend: { async load() { return null; }, async store() {}, async clear() {} },
+        childResolver: { resolve() { return null; } },
+    });
+
+    // Simulate a paired + child-selected device without touching the network.
+    daemon._credentials = { userId: 'owner-uuid', pairId: 7, pairToken: 'pair-secret', children: [] };
+    daemon._childId = 'selected-child';
+
+    let apiParams = null;
+    daemon._api.reportAuthEvent = async (params) => { apiParams = params; return { status: 'success' }; };
+
+    let emitted = null;
+    daemon.on('auth-event-reported', (e) => { emitted = e; });
+
+    const res = await daemon.reportAuthEvent({ method: 'offline_code' });
+
+    assert.equal(res.status, 'success');
+    assert.deepEqual(apiParams, {
+        userId: 'owner-uuid',
+        pairId: 7,
+        pairToken: 'pair-secret',
+        childId: 'selected-child',   // defaulted from the selected child
+        method: 'offline_code',
+    });
+    assert.deepEqual(emitted, { childId: 'selected-child', method: 'offline_code' });
+});
+
+test('DeviceDaemon.reportAuthEvent throws when the device is not paired', async () => {
+    const daemon = new DeviceDaemon({
+        activities: [{ id: 1 }],
+        credentialBackend: { async load() { return null; }, async store() {}, async clear() {} },
+        childResolver: { resolve() { return null; } },
+    });
+    daemon._credentials = null;
+
+    await assert.rejects(() => daemon.reportAuthEvent({ method: 'pin' }), /not paired/i);
+});