@camstack/server 1.2.605 → 1.2.606

package/dist/core/auth/share-token.service.js

@@ -1,459 +0,0 @@
-"use strict";
-var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    var desc = Object.getOwnPropertyDescriptor(m, k);
-    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
-      desc = { enumerable: true, get: function() { return m[k]; } };
-    }
-    Object.defineProperty(o, k2, desc);
-}) : (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    o[k2] = m[k];
-}));
-var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
-    Object.defineProperty(o, "default", { enumerable: true, value: v });
-}) : function(o, v) {
-    o["default"] = v;
-});
-var __importStar = (this && this.__importStar) || (function () {
-    var ownKeys = function(o) {
-        ownKeys = Object.getOwnPropertyNames || function (o) {
-            var ar = [];
-            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
-            return ar;
-        };
-        return ownKeys(o);
-    };
-    return function (mod) {
-        if (mod && mod.__esModule) return mod;
-        var result = {};
-        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
-        __setModuleDefault(result, mod);
-        return result;
-    };
-})();
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.ShareTokenService = exports.ShareTokenRecordSchema = exports.ShareTokenScopeSchema = exports.SHARE_TOKEN_MAX_DEVICES = exports.SHARE_TOKEN_TTL_DEFAULT_SEC = exports.SHARE_TOKEN_TTL_MAX_SEC = exports.SHARE_TOKEN_TTL_MIN_SEC = exports.SHARE_TOKEN_PREFIX = void 0;
-/**
- * ShareTokenService — scoped, TTL'd VIEW tokens for standalone share links
- * (grid rework R6: the embed page opened by a third party authenticates with
- * a `csv_*` token carried in the share URL's `#t=` fragment).
- *
- * Design mirrors the existing `cst_*` scoped-token mechanism
- * (`@camstack/system` ScopedTokenManager): a random opaque token, stored
- * server-side as a SHA-256 hash so a DB leak never exposes live tokens,
- * validated per request, revocable, with the TTL enforced at verification.
- *
- * Differences from `cst_*` tokens — a share token is NOT a user session:
- *   • it resolves to a RESTRICTED `share-view` principal (see
- *     `trpc.context.ts`) that can only call the allowlisted embed surface
- *     (`share-view-access.ts`), never the general cap surface;
- *   • the scope is a share grant (`kind: 'grid-view'` + deviceIds), not a
- *     capability/addon grant;
- *   • expiry is explicit at mint time: a bounded TTL (60s..30d, default
- *     7d) or the deliberate `ttlSec: 'never'` choice (`expiresAt: null`)
- *     for permanently-shared grids — revocation stays the kill switch.
- *
- * Storage: the hub's settings backend (same SQLite store the scoped tokens
- * live in, reached directly instead of over the settings-store cap since
- * this service is hub-resident). Collection: `share_view_tokens`.
- */
-const crypto = __importStar(require("node:crypto"));
-const zod_1 = require("zod");
-const types_1 = require("@camstack/types");
-const record_kinds_js_1 = require("./record-kinds.js");
-/**
- * @durable class=config owner=core-auth
- *   write="a user mints a share link; and a best-effort lastUsedAt touch on every successful validation"
- *   retention="none — no sweep and no TTL reaper. A row goes only when the owner or an admin revokes it. expiresAt is enforced at VALIDATION, so an expired token keeps its row and keeps being scanned; the table is bounded only by how many links people mint."
- */
-const SHARE_TOKENS_COLLECTION = 'share_view_tokens';
-/**
- * The two predicates this service actually issues, indexed.
- *
- * The collection is KV-shaped — `(id TEXT PK, data TEXT)` — so `tokenHash` and
- * `userId` live inside the `data` blob and the backend rewrites both predicates
- * to `json_extract`. Declaring an index on a blob field makes the backend emit
- * a matching EXPRESSION index (`sqlite-settings-backend.ts`, `ensureTable`),
- * which is the only kind SQLite can use for these queries.
- *
- * Why it matters: `validate()` runs on EVERY request carrying a `csv_*` token,
- * and without this it was a full-table scan that parsed the JSON of every row
- * to compare one hash. Six rows today, so it never showed up — but it is the
- * authentication path for share links, so it is the one that gets hit hardest
- * the day a link is shared widely.
- *
- * Adding indexes is NOT a shape change: the column list is untouched, so
- * `ensureTable` takes neither the rebuild nor the `ALTER TABLE` branch, and no
- * row is migrated or lost.
- */
-const SHARE_TOKENS_INDEXES = [
-    { name: 'idx_share_view_tokens_hash', columns: ['tokenHash'] },
-    { name: 'idx_share_view_tokens_user', columns: ['userId'] },
-];
-/** Wire prefix — `csv_` = CamStack Share View (cf. `cst_` scoped tokens). */
-exports.SHARE_TOKEN_PREFIX = 'csv_';
-// ── TTL / scope bounds (enforced at mint, re-checked by the router schema) ──
-exports.SHARE_TOKEN_TTL_MIN_SEC = 60;
-exports.SHARE_TOKEN_TTL_MAX_SEC = 30 * 24 * 60 * 60; // 30 days
-exports.SHARE_TOKEN_TTL_DEFAULT_SEC = 7 * 24 * 60 * 60; // 7 days
-exports.SHARE_TOKEN_MAX_DEVICES = 64;
-/**
- * What a share token is allowed to see. Keyed on `kind` so future share
- * surfaces (single-camera view, recording clip, …) extend the set without
- * touching verification plumbing.
- */
-/**
- * `grid-view` — the live camera wall (WebRTC + snapshots).
- * `events-view` — the events embed (track feed, kind taxonomy, CLIP search).
- *
- * They are SEPARATE kinds, not one kind with a bigger surface. Adding the
- * track methods to `grid-view` would retroactively widen every share link an
- * operator has already handed out: a link minted to show a camera wall would
- * silently start serving that camera's event history. A token keeps the
- * perimeter it was minted with, and a new perimeter needs a new mint.
- *
- * Neither kind is a superset of the other — an events link cannot open a
- * WebRTC session, and a grid link cannot read a track.
- */
-exports.ShareTokenScopeSchema = zod_1.z.object({
-    kind: zod_1.z.enum(types_1.SHARE_VIEW_KINDS),
-    deviceIds: zod_1.z.array(zod_1.z.number().int().nonnegative()).min(1).max(exports.SHARE_TOKEN_MAX_DEVICES),
-    /**
-     * TALK-BACK, opt-in at mint time. Absent means OFF, and that is the whole
-     * point: a share link is handed to third parties, so the difference between
-     * "can watch the kitchen" and "can speak into the kitchen" must be a choice
-     * somebody made for THAT link, on the day they made it.
-     *
-     * It rides on the scope rather than widening the grid enumeration because
-     * the enumeration is retroactive: a method added there is granted to every
-     * token ever minted, including the one handed to a neighbour last week.
-     * `share-view-access.ts` says so about event history; the same rule with
-     * actuation into the home on the other end of it is not a smaller matter.
-     *
-     * It widens WHAT may be called, never WHICH cameras — `deviceIds` still
-     * gates every talk call.
-     */
-    talk: zod_1.z.boolean().optional(),
-});
-/** Persisted record — never leaves the server with `tokenHash` attached. */
-exports.ShareTokenRecordSchema = zod_1.z.object({
-    id: zod_1.z.string(),
-    /** The user that minted the share link (owner — may revoke it). */
-    userId: zod_1.z.string(),
-    tokenHash: zod_1.z.string(),
-    /** First 12 chars of the raw token — display/audit label only. */
-    tokenPrefix: zod_1.z.string(),
-    scope: exports.ShareTokenScopeSchema,
-    createdAt: zod_1.z.number(),
-    /** Epoch ms — or `null` for a never-expiring token (explicit choice at mint). */
-    expiresAt: zod_1.z.number().nullable(),
-    lastUsedAt: zod_1.z.number().optional(),
-});
-function parseShareToken(data) {
-    const parsed = exports.ShareTokenRecordSchema.safeParse(data);
-    return parsed.success ? parsed.data : null;
-}
-function recordToBody(record) {
-    const { id: _id, ...body } = record;
-    return body;
-}
-function rowToRecord(id, body) {
-    return exports.ShareTokenRecordSchema.safeParse({ id, ...body }).data ?? null;
-}
-async function readAllShareTokenRows(kind, where) {
-    const out = [];
-    let cursor;
-    for (let page = 0; page < 100; page += 1) {
-        const answer = await kind.query({
-            ...(where === undefined ? {} : { where }),
-            limit: 1000,
-            ...(cursor === undefined ? {} : { cursor }),
-        });
-        out.push(...answer.records);
-        if (answer.nextCursor === null)
-            return out;
-        cursor = answer.nextCursor;
-    }
-    throw new Error('share-view-tokens: row count exceeds pagination bound');
-}
-class ShareTokenService {
-    getStore;
-    logger;
-    /**
-     * Declaration is one-time per process; reset only if the backend itself
-     * is swapped (it never is at runtime — the getter is lazy solely because
-     * the sqlite builtin registers after this service is constructed).
-     */
-    collectionDeclared = false;
-    resolveKind;
-    constructor(getStore, logger = null, resolveKind = () => null) {
-        this.getStore = getStore;
-        this.logger = logger;
-        this.resolveKind = resolveKind;
-    }
-    /** Hub wiring after `records.forOwner('core-auth').declare(...)`. */
-    bindShareTokensKind(resolver) {
-        this.resolveKind = resolver;
-        this.collectionDeclared = true;
-    }
-    kind() {
-        return this.resolveKind();
-    }
-    async findById(id) {
-        const kind = this.kind();
-        if (kind !== null) {
-            const row = await kind.get(id);
-            return row === null ? null : rowToRecord(row.id, row.data);
-        }
-        const results = await (await this.store()).query({
-            collection: SHARE_TOKENS_COLLECTION,
-            filter: { where: { id } },
-        });
-        const first = results[0];
-        return first === undefined ? null : parseShareToken(first.data);
-    }
-    async persistRecord(record) {
-        const kind = this.kind();
-        if (kind !== null) {
-            const parsed = record_kinds_js_1.coreAuthRecordKinds['share-view-tokens'].schema.safeParse(recordToBody(record));
-            if (!parsed.success)
-                throw new Error(parsed.error.message);
-            await kind.put({
-                id: record.id,
-                expiresAt: record.expiresAt ?? undefined,
-                data: parsed.data,
-            });
-            return;
-        }
-        await (await this.store()).update({
-            collection: SHARE_TOKENS_COLLECTION,
-            id: record.id,
-            data: { ...record },
-        });
-    }
-    async deleteById(id) {
-        const kind = this.kind();
-        if (kind !== null) {
-            await kind.delete(id);
-            return;
-        }
-        await (await this.store()).delete({ collection: SHARE_TOKENS_COLLECTION, key: id });
-    }
-    /**
-     * Resolve the backend AND ensure `share_view_tokens` is declared before
-     * the first operation. The structured settings backend fail-closes on
-     * undeclared collections; this KV shape (`id` PK + `data` TEXT) is
-     * byte-identical to what the legacy on-demand path created, so existing
-     * rows keep working with no migration.
-     */
-    async store() {
-        if (this.kind() !== null) {
-            const store = this.getStore();
-            if (!store) {
-                throw new Error('Share tokens unavailable — settings backend not ready');
-            }
-            return store;
-        }
-        const store = this.getStore();
-        if (!store) {
-            throw new Error('Share tokens unavailable — settings backend not ready');
-        }
-        if (!this.collectionDeclared) {
-            await store.declareCollection({
-                collection: SHARE_TOKENS_COLLECTION,
-                columns: [
-                    { name: 'id', type: 'TEXT', primaryKey: true, notNull: true },
-                    { name: 'data', type: 'TEXT', notNull: true },
-                ],
-                indexes: SHARE_TOKENS_INDEXES,
-            });
-            this.collectionDeclared = true;
-        }
-        return store;
-    }
-    /**
-     * Mint a new share token. Throws on invalid scope or out-of-bounds TTL
-     * (fail fast — the router's Zod input schema should have caught both).
-     * `ttlSec: 'never'` is the explicit opt-in to a never-expiring token
-     * (`expiresAt: null`); omitted falls back to the 7-day default.
-     * Returns the RAW token exactly once; only its hash is persisted.
-     */
-    async create(input) {
-        const scope = exports.ShareTokenScopeSchema.parse(input.scope);
-        const ttlSec = input.ttlSec ?? exports.SHARE_TOKEN_TTL_DEFAULT_SEC;
-        if (ttlSec !== 'never' &&
-            (!Number.isInteger(ttlSec) ||
-                ttlSec < exports.SHARE_TOKEN_TTL_MIN_SEC ||
-                ttlSec > exports.SHARE_TOKEN_TTL_MAX_SEC)) {
-            throw new Error(`Share token TTL out of bounds — got ${ttlSec}s, allowed ` +
-                `[${exports.SHARE_TOKEN_TTL_MIN_SEC}s, ${exports.SHARE_TOKEN_TTL_MAX_SEC}s] or 'never'`);
-        }
-        const rawToken = `${exports.SHARE_TOKEN_PREFIX}${crypto.randomBytes(32).toString('hex')}`;
-        const now = Date.now();
-        const record = {
-            id: crypto.randomUUID(),
-            userId: input.userId,
-            tokenHash: crypto.createHash('sha256').update(rawToken).digest('hex'),
-            tokenPrefix: rawToken.slice(0, 12),
-            scope,
-            createdAt: now,
-            expiresAt: ttlSec === 'never' ? null : now + ttlSec * 1000,
-        };
-        const kind = this.kind();
-        if (kind !== null) {
-            const parsed = record_kinds_js_1.coreAuthRecordKinds['share-view-tokens'].schema.safeParse(recordToBody(record));
-            if (!parsed.success)
-                throw new Error(parsed.error.message);
-            await kind.put({
-                id: record.id,
-                expiresAt: record.expiresAt ?? undefined,
-                data: parsed.data,
-            });
-        }
-        else {
-            await (await this.store()).insert({
-                collection: SHARE_TOKENS_COLLECTION,
-                record: { id: record.id, data: { ...record } },
-            });
-        }
-        this.logger?.info('Share token minted', {
-            meta: {
-                id: record.id,
-                userId: record.userId,
-                kind: scope.kind,
-                deviceIds: scope.deviceIds,
-                expiresAt: record.expiresAt,
-            },
-        });
-        return { token: rawToken, record };
-    }
-    /**
-     * Resolve a raw `csv_*` token to its record. Returns `null` for:
-     * wrong prefix, unknown token, corrupt record, or expired token.
-     * Never throws on bad input — the auth boundary treats `null` as 401.
-     */
-    async validate(rawToken) {
-        if (!rawToken.startsWith(exports.SHARE_TOKEN_PREFIX))
-            return null;
-        const tokenHash = crypto.createHash('sha256').update(rawToken).digest('hex');
-        const kind = this.kind();
-        let record = null;
-        if (kind !== null) {
-            const page = await kind.query({ where: { tokenHash }, limit: 1 });
-            const row = page.records[0];
-            record = row === undefined ? null : rowToRecord(row.id, row.data);
-        }
-        else {
-            const results = await (await this.store()).query({
-                collection: SHARE_TOKENS_COLLECTION,
-                filter: { where: { tokenHash } },
-            });
-            const first = results[0];
-            record = first === undefined ? null : parseShareToken(first.data);
-        }
-        if (record === null)
-            return null;
-        // `expiresAt: null` = never expires (explicit mint-time choice);
-        // revocation remains the kill switch for those.
-        if (record.expiresAt !== null && Date.now() > record.expiresAt)
-            return null;
-        this.touchLastUsed(record).catch(() => {
-            /* best-effort audit timestamp — never block validation */
-        });
-        return record;
-    }
-    /**
-     * Slide `expiresAt` forward from NOW for a still-valid token. Same raw
-     * credential, same id — Home Assistant remints without flooding
-     * `share_view_tokens`. Throws when missing, expired, never-expiring,
-     * or the caller is not the owner/admin; refuses `'never'` as ttlSec.
-     */
-    async extend(input) {
-        if (!Number.isInteger(input.ttlSec) ||
-            input.ttlSec < exports.SHARE_TOKEN_TTL_MIN_SEC ||
-            input.ttlSec > exports.SHARE_TOKEN_TTL_MAX_SEC) {
-            throw new Error(`Share token TTL out of bounds — got ${input.ttlSec}s, allowed ` +
-                `[${exports.SHARE_TOKEN_TTL_MIN_SEC}s, ${exports.SHARE_TOKEN_TTL_MAX_SEC}s]`);
-        }
-        const record = await this.findById(input.id);
-        if (record === null) {
-            throw (0, types_1.userError)('auth.share-token-not-found', { id: input.id }, `Share token not found: ${input.id}`);
-        }
-        if (!input.callerIsAdmin && record.userId !== input.callerUserId) {
-            throw (0, types_1.userError)('auth.share-owner-only-extend', undefined, 'Only the token owner or an admin can extend a share token');
-        }
-        if (record.expiresAt === null) {
-            throw (0, types_1.userError)('auth.share-never-expiring-extend', undefined, 'A never-expiring share token cannot be extended');
-        }
-        const now = Date.now();
-        if (now > record.expiresAt) {
-            throw (0, types_1.userError)('server.share-token-expired', { id: String(input.id) }, `Share token expired: ${input.id}`);
-        }
-        const updated = {
-            ...record,
-            expiresAt: now + input.ttlSec * 1000,
-        };
-        await this.persistRecord(updated);
-        this.logger?.info('Share token extended', {
-            meta: {
-                id: updated.id,
-                byUserId: input.callerUserId,
-                expiresAt: updated.expiresAt,
-            },
-        });
-        return updated;
-    }
-    /**
-     * Revoke (delete) a share token. Only the minting user or an admin may
-     * revoke. Returns `false` when the token doesn't exist; throws on a
-     * permission mismatch so the router surfaces a FORBIDDEN.
-     */
-    async revoke(input) {
-        const record = await this.findById(input.id);
-        if (record === null)
-            return false;
-        if (!input.callerIsAdmin && record.userId !== input.callerUserId) {
-            throw (0, types_1.userError)('auth.share-owner-only-revoke', undefined, 'Only the token owner or an admin can revoke a share token');
-        }
-        await this.deleteById(input.id);
-        this.logger?.info('Share token revoked', {
-            meta: { id: record.id, byUserId: input.callerUserId },
-        });
-        return true;
-    }
-    /** Every share token minted by `userId`, expired ones included. */
-    async listForUser(userId) {
-        const kind = this.kind();
-        if (kind !== null) {
-            const rows = await readAllShareTokenRows(kind, { userId });
-            return rows
-                .map((row) => rowToRecord(row.id, row.data))
-                .filter((r) => r !== null);
-        }
-        const results = await (await this.store()).query({
-            collection: SHARE_TOKENS_COLLECTION,
-            filter: { where: { userId } },
-        });
-        return results.map((r) => parseShareToken(r.data)).filter((r) => r !== null);
-    }
-    /** All share tokens (admin listing). */
-    async listAll() {
-        const kind = this.kind();
-        if (kind !== null) {
-            const rows = await readAllShareTokenRows(kind);
-            return rows
-                .map((row) => rowToRecord(row.id, row.data))
-                .filter((r) => r !== null);
-        }
-        const results = await (await this.store()).query({
-            collection: SHARE_TOKENS_COLLECTION,
-            filter: {},
-        });
-        return results.map((r) => parseShareToken(r.data)).filter((r) => r !== null);
-    }
-    async touchLastUsed(record) {
-        await this.persistRecord({ ...record, lastUsedAt: Date.now() });
-    }
-}
-exports.ShareTokenService = ShareTokenService;