@vitrinka/link 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,7 @@
+# @vitrinka/link
+
+## 0.1.0
+
+- Initial release: `startLink`, `pollLink`, `linkOrigin`, `isUnauthorized`,
+  `LinkExpired` — the device-link flow shared by `@vitrinka/web` and
+  `@vitrinka/expo`.

package/LICENSE

@@ -0,0 +1,93 @@
+Elastic License 2.0
+
+URL: https://www.elastic.co/licensing/elastic-license
+
+## Acceptance
+
+By using the software, you agree to all of the terms and conditions below.
+
+## Copyright License
+
+The licensor grants you a non-exclusive, royalty-free, worldwide,
+non-sublicensable, non-transferable license to use, copy, distribute, make
+available, and prepare derivative works of the software, in each case subject to
+the limitations and conditions below.
+
+## Limitations
+
+You may not provide the software to third parties as a hosted or managed
+service, where the service provides users with access to any substantial set of
+the features or functionality of the software.
+
+You may not move, change, disable, or circumvent the license key functionality
+in the software, and you may not remove or obscure any functionality in the
+software that is protected by the license key.
+
+You may not alter, remove, or obscure any licensing, copyright, or other notices
+of the licensor in the software. Any use of the licensor’s trademarks is subject
+to applicable law.
+
+## Patents
+
+The licensor grants you a license, under any patent claims the licensor can
+license, or becomes able to license, to make, have made, use, sell, offer for
+sale, import and have imported the software, in each case subject to the
+limitations and conditions in this license. This license does not cover any
+patent claims that you cause to be infringed by modifications or additions to
+the software. If you or your company make any written claim that the software
+infringes or contributes to infringement of any patent, your patent license for
+the software granted under these terms ends immediately. If your company makes
+such a claim, your patent license ends immediately for work on behalf of your
+company.
+
+## Notices
+
+You must ensure that anyone who gets a copy of any part of the software from you
+also gets a copy of these terms.
+
+If you modify the software, you must include in any modified copies of the
+software prominent notices stating that you have modified the software.
+
+## No Other Rights
+
+These terms do not imply any licenses other than those expressly granted in
+these terms.
+
+## Termination
+
+If you use the software in violation of these terms, such use is not licensed,
+and your licenses will automatically terminate. If the licensor provides you
+with a notice of your violation, and you cease all violation of this license no
+later than 30 days after you receive that notice, your licenses will be
+reinstated retroactively. However, if you violate these terms after such
+reinstatement, any additional violation of these terms will cause your licenses
+to terminate automatically and permanently.
+
+## No Liability
+
+*As far as the law allows, the software comes as is, without any warranty or
+condition, and the licensor will not be liable to you for any damages arising
+out of these terms or the use or nature of the software, under any kind of
+legal claim.*
+
+## Definitions
+
+The **licensor** is the entity offering these terms, and the **software** is the
+software the licensor makes available under these terms, including any portion
+of it.
+
+**you** refers to the individual or entity agreeing to these terms.
+
+**your company** is any legal entity, sole proprietorship, or other kind of
+organization that you work for, plus all organizations that have control over,
+are under the control of, or are under common control with that organization.
+**control** means ownership of substantially all the assets of an entity, or the
+power to direct its management and policies by vote, contract, or otherwise.
+Control can be direct or indirect.
+
+**your licenses** are all the licenses granted to you for the software under
+these terms.
+
+**use** means anything you do with the software requiring one of your licenses.
+
+**trademark** means trademarks, service marks, and similar rights.

package/README.md

@@ -0,0 +1,23 @@
+# @vitrinka/link
+
+The device link both vitrinka recorders authenticate with: the recorder asks
+the server for a short code, the tester approves it in vitrinka (same device
+via a link, or another device via the server-rendered QR), and the recorder
+receives an ingest-only `vkr_` token. No baked secrets, no QR library.
+
+```ts
+import { startLink, pollLink, LinkExpired } from '@vitrinka/link';
+
+const start = await startLink('https://app.vitrinka.ai/w/acme', { label: 'Safari on macOS · app.example.test' });
+start.user_code;  // 'ABCD-EFGH' — show it
+start.verifyUrl;  // open on the same device
+start.qrUrl;      // <img src> for the desktop→phone path (SVG from the server)
+const linked = await pollLink(start.base, start.device_code, { interval: start.interval });
+linked.token;     // 'vkr_…' — store it, send it as the bearer
+```
+
+Doors (at the base URL's origin): `POST /api/v1/cli/auth {kind:"recorder",label}` →
+201 `{device_code, user_code, verify_path, verify_url?, qr_path, interval,
+expires_in}`; `POST /api/v1/cli/auth/claim {device_code}` → 202 pending ·
+200 `{token, workspace, label, expires_at}` · 404 expired (`LinkExpired`).
+A 401 from any session door means the token is dead: forget it and link again.

package/build/index.d.ts

@@ -0,0 +1,76 @@
+/**
+ * @vitrinka/link — the device link that mints an ingest-only recorder token.
+ *
+ * Doors live at the ORIGIN of the configured base (a base may be
+ * `https://app.vitrinka.ai/w/acme`; the link doors sit at the apex):
+ *
+ *   POST {origin}/api/v1/cli/auth        {kind:"recorder", label}
+ *     → 201 {device_code, user_code, verify_path, verify_url?, qr_path, interval, expires_in}
+ *   POST {origin}/api/v1/cli/auth/claim  {device_code}
+ *     → 202 pending · 200 {token, workspace, label, expires_at} · 404 expired
+ *
+ * Pure TypeScript: no DOM or React Native globals — `fetch` is taken from
+ * the options or from globalThis.
+ */
+export interface LinkStart {
+    /** The base the link was started for (its origin serves the doors). */
+    base: string;
+    device_code: string;
+    /** The code the tester types/sees, e.g. `ABCD-EFGH`. */
+    user_code: string;
+    verify_path: string;
+    /** Absolute approval URL — same-device path. */
+    verifyUrl: string;
+    /** Absolute URL of the server-rendered QR (SVG) — other-device path. */
+    qrUrl: string;
+    /** Poll interval in seconds (never below 2). */
+    interval: number;
+    expires_in: number;
+}
+export interface Linked {
+    token: string;
+    workspace: string;
+    label: string;
+    expires_at: string;
+}
+/** The server no longer knows the code (expired or already consumed). */
+export declare class LinkExpired extends Error {
+    constructor(message?: string);
+}
+export declare class LinkError extends Error {
+    readonly status: number;
+    constructor(message: string, status: number);
+}
+/**
+ * Transport-status vocabulary shared by every recorder (web, Expo) — ONE copy,
+ * here in the zero-dependency package both already depend on, so a change to
+ * the retry rule cannot drift between them.
+ */
+export declare class VitrinkaApiError extends Error {
+    readonly status: number;
+    constructor(message: string, status: number);
+}
+/** A server verdict retrying can never fix (4xx minus timeout/rate-limit). */
+export declare function permanentStatus(status: number): boolean;
+type Fetch = typeof globalThis.fetch;
+export interface LinkOptions {
+    fetch?: Fetch;
+}
+/** The control-plane origin of a base URL. */
+export declare function linkOrigin(base: string): string;
+/** A 401 from a session door: the stored token is dead. */
+export declare function isUnauthorized(status: number): boolean;
+/** Ask the server for a link code. */
+export declare function startLink(base: string, opts: {
+    label: string;
+} & LinkOptions): Promise<LinkStart>;
+export interface PollOptions extends LinkOptions {
+    /** Seconds between claims (min 2). */
+    interval?: number;
+    signal?: AbortSignal;
+    /** Test seam: the sleep. */
+    sleep?: (ms: number, signal?: AbortSignal) => Promise<void>;
+}
+/** Claim until approved. Resolves with the token; throws LinkExpired on 404, AbortError on abort. */
+export declare function pollLink(base: string, deviceCode: string, opts?: PollOptions): Promise<Linked>;
+export {};

package/build/index.js

@@ -0,0 +1,176 @@
+/**
+ * @vitrinka/link — the device link that mints an ingest-only recorder token.
+ *
+ * Doors live at the ORIGIN of the configured base (a base may be
+ * `https://app.vitrinka.ai/w/acme`; the link doors sit at the apex):
+ *
+ *   POST {origin}/api/v1/cli/auth        {kind:"recorder", label}
+ *     → 201 {device_code, user_code, verify_path, verify_url?, qr_path, interval, expires_in}
+ *   POST {origin}/api/v1/cli/auth/claim  {device_code}
+ *     → 202 pending · 200 {token, workspace, label, expires_at} · 404 expired
+ *
+ * Pure TypeScript: no DOM or React Native globals — `fetch` is taken from
+ * the options or from globalThis.
+ */
+/** The server no longer knows the code (expired or already consumed). */
+export class LinkExpired extends Error {
+    constructor(message = 'link code expired') {
+        super(message);
+        this.name = 'LinkExpired';
+    }
+}
+export class LinkError extends Error {
+    constructor(message, status) {
+        super(message);
+        this.status = status;
+        this.name = 'LinkError';
+    }
+}
+/**
+ * Transport-status vocabulary shared by every recorder (web, Expo) — ONE copy,
+ * here in the zero-dependency package both already depend on, so a change to
+ * the retry rule cannot drift between them.
+ */
+export class VitrinkaApiError extends Error {
+    constructor(message, status) {
+        super(message);
+        this.status = status;
+        this.name = 'VitrinkaApiError';
+    }
+}
+/** A server verdict retrying can never fix (4xx minus timeout/rate-limit). */
+export function permanentStatus(status) {
+    return status >= 400 && status < 500 && status !== 408 && status !== 429;
+}
+/** The control-plane origin of a base URL. */
+export function linkOrigin(base) {
+    return new URL(base).origin;
+}
+/** A 401 from a session door: the stored token is dead. */
+export function isUnauthorized(status) {
+    return status === 401;
+}
+function fetcher(opts) {
+    const f = opts.fetch ?? globalThis.fetch;
+    if (typeof f !== 'function')
+        throw new Error('vitrinka link: no fetch available');
+    return f;
+}
+/**
+ * Resolve a server-supplied path or URL against the link origin and accept it
+ * ONLY when it lands on that same origin over http(s). The result is rendered
+ * as a clickable href and an <img src>, so a compromised or misconfigured
+ * server must not be able to point the tester's tap or the QR anywhere else.
+ * Anything off-origin, non-http or unparsable falls back to the origin's own
+ * path (or, when even that is unusable, to the given default).
+ */
+function sameOriginUrl(origin, candidate, fallbackPath, defaultPath) {
+    const own = (v) => {
+        if (!v)
+            return undefined;
+        try {
+            const u = new URL(v, origin);
+            if (u.protocol !== 'http:' && u.protocol !== 'https:')
+                return undefined;
+            if (u.origin === origin)
+                return u.href;
+            // Same path, OUR origin: a server that answered with another host's URL
+            // still gets the tap and the QR pointed at the deployment we linked to.
+            return origin + u.pathname + u.search;
+        }
+        catch {
+            return undefined;
+        }
+    };
+    return own(candidate) ?? own(fallbackPath) ?? origin + defaultPath;
+}
+function requireString(w, key, status) {
+    const v = w[key];
+    if (typeof v !== 'string' || v === '')
+        throw new LinkError(`link start → malformed payload (${key})`, status);
+    return v;
+}
+/** Ask the server for a link code. */
+export async function startLink(base, opts) {
+    const origin = linkOrigin(base);
+    const res = await fetcher(opts)(`${origin}/api/v1/cli/auth`, {
+        method: 'POST',
+        mode: 'cors',
+        credentials: 'omit',
+        headers: { 'content-type': 'application/json' },
+        body: JSON.stringify({ kind: 'recorder', label: opts.label }),
+    });
+    if (res.status !== 201 && res.status !== 200) {
+        throw new LinkError(`link start → ${res.status}`, res.status);
+    }
+    let raw;
+    try {
+        raw = await res.json();
+    }
+    catch {
+        throw new LinkError('link start → malformed payload (not JSON)', res.status);
+    }
+    if (typeof raw !== 'object' || raw === null)
+        throw new LinkError('link start → malformed payload', res.status);
+    const w = raw;
+    const deviceCode = requireString(w, 'device_code', res.status);
+    const userCode = requireString(w, 'user_code', res.status);
+    const verifyPath = requireString(w, 'verify_path', res.status);
+    const qrPath = requireString(w, 'qr_path', res.status);
+    return {
+        base,
+        device_code: deviceCode,
+        user_code: userCode,
+        verify_path: verifyPath,
+        verifyUrl: sameOriginUrl(origin, typeof w.verify_url === 'string' ? w.verify_url : undefined, verifyPath, `/cli-auth?code=${encodeURIComponent(userCode)}`),
+        qrUrl: sameOriginUrl(origin, qrPath, qrPath, `/cli-auth/qr?code=${encodeURIComponent(userCode)}`),
+        interval: Math.max(2, Number(w.interval) || 2),
+        expires_in: Number(w.expires_in) || 0,
+    };
+}
+function defaultSleep(ms, signal) {
+    return new Promise((res, rej) => {
+        if (signal?.aborted)
+            return rej(abortError());
+        const t = setTimeout(() => {
+            signal?.removeEventListener('abort', onAbort);
+            res();
+        }, ms);
+        const onAbort = () => {
+            clearTimeout(t);
+            rej(abortError());
+        };
+        signal?.addEventListener('abort', onAbort, { once: true });
+    });
+}
+function abortError() {
+    const e = new Error('link polling aborted');
+    e.name = 'AbortError';
+    return e;
+}
+/** Claim until approved. Resolves with the token; throws LinkExpired on 404, AbortError on abort. */
+export async function pollLink(base, deviceCode, opts = {}) {
+    const origin = linkOrigin(base);
+    const f = fetcher(opts);
+    const sleep = opts.sleep ?? defaultSleep;
+    const interval = Math.max(2, opts.interval ?? 2);
+    for (;;) {
+        if (opts.signal?.aborted)
+            throw abortError();
+        const res = await f(`${origin}/api/v1/cli/auth/claim`, {
+            method: 'POST',
+            mode: 'cors',
+            credentials: 'omit',
+            headers: { 'content-type': 'application/json' },
+            body: JSON.stringify({ device_code: deviceCode }),
+            signal: opts.signal,
+        });
+        if (res.status === 200)
+            return (await res.json());
+        if (res.status === 404 || res.status === 410)
+            throw new LinkExpired();
+        if (res.status !== 202)
+            throw new LinkError(`link claim → ${res.status}`, res.status);
+        await sleep(interval * 1000, opts.signal);
+    }
+}

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@vitrinka/link",
+  "version": "0.1.0",
+  "description": "vitrinka device link — the Netflix-style code flow that mints an ingest-only recorder token for the web and Expo recorders. Zero dependencies.",
+  "license": "Elastic-2.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/henderson-tech/vitrinka-kit.git",
+    "directory": "packages/link"
+  },
+  "type": "module",
+  "source": "src/index.ts",
+  "main": "build/index.js",
+  "types": "build/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./build/index.d.ts",
+      "default": "./build/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": ["build", "README.md", "CHANGELOG.md"],
+  "sideEffects": false,
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit",
+    "test": "bun test src",
+    "prepublishOnly": "tsc -p tsconfig.build.json"
+  },
+  "devDependencies": {
+    "@types/bun": "^1.2.0",
+    "@types/node": "^22.0.0",
+    "typescript": "~6.0.3"
+  },
+  "keywords": ["vitrinka", "device-link", "recorder"]
+}