@vitrinka/link 0.1.0 → 0.1.1

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # @vitrinka/link
 
+## 0.1.1
+
+- **Workspace hint.** `linkWorkspace(base)` reads the `<slug>` of a
+  `/w/<slug>` base; `startLink(base, { workspace })` appends
+  `workspace=<slug>` to `verifyUrl` and `qrUrl` so the approve page
+  preselects it (the start body stays `{kind, label}`), and
+  `pollLink(base, code, { workspace })` rejects a claim pinned to any other
+  workspace with `LinkWorkspaceMismatch` — its token is never returned. It
+  fails closed: a claim that names no workspace is refused too. A base
+  without `/w/<slug>` behaves as before.
+- `Linked` matches the claim the server sends: `expires_in` (seconds), not
+  the never-sent `expires_at`.
+
 ## 0.1.0
 
 - Initial release: `startLink`, `pollLink`, `linkOrigin`, `isUnauthorized`,

package/README.md

@@ -6,18 +6,26 @@ 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';
+import { startLink, pollLink, linkWorkspace, LinkExpired, LinkWorkspaceMismatch } from '@vitrinka/link';
 
-const start = await startLink('https://app.vitrinka.ai/w/acme', { label: 'Safari on macOS · app.example.test' });
+const base = 'https://app.vitrinka.ai/w/acme';
+const workspace = linkWorkspace(base); // 'acme' — undefined for a bare origin
+const start = await startLink(base, { label: 'Safari on macOS · app.example.test', workspace });
 start.user_code;  // 'ABCD-EFGH' — show it
-start.verifyUrl;  // open on the same device
+start.verifyUrl;  // open on the same device (…&workspace=acme preselects it)
 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 });
+const linked = await pollLink(start.base, start.device_code, { interval: start.interval, workspace });
 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`).
+200 `{token, kind, workspace, label, expires_in}` · 404 expired (`LinkExpired`).
 A 401 from any session door means the token is dead: forget it and link again.
+
+A token only authenticates in the workspace it was approved into, so a
+`/w/<slug>` base passes that slug as `workspace`: it rides the approve and QR
+URLs as a `workspace=<slug>` preselect (never the start body), and a claim
+approved into another workspace rejects with `LinkWorkspaceMismatch`
+(`linked`, `expected`, a ready-to-show message) — the token is discarded.

package/build/index.d.ts

@@ -7,7 +7,12 @@
  *   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
+ *     → 202 pending · 200 {token, kind, workspace, label, expires_in} · 404 expired
+ *
+ * A base that addresses one workspace (`…/w/<slug>`) carries that slug as a
+ * `workspace=<slug>` hint on the approve and QR URLs (the approve page
+ * preselects it) and refuses a claim pinned to any other workspace — its
+ * token could never authenticate against `/w/<slug>`.
  *
  * Pure TypeScript: no DOM or React Native globals — `fetch` is taken from
  * the options or from globalThis.
@@ -29,14 +34,26 @@ export interface LinkStart {
 }
 export interface Linked {
     token: string;
+    /** Slug of the workspace the approver pinned the token to. */
     workspace: string;
     label: string;
-    expires_at: string;
+    /** Seconds until the (sliding) token expiry, as of the claim. */
+    expires_in: number;
 }
 /** The server no longer knows the code (expired or already consumed). */
 export declare class LinkExpired extends Error {
     constructor(message?: string);
 }
+/**
+ * The approver pinned the token to another workspace than the one the
+ * recorder records into. The token is discarded (never returned): every
+ * session door under `/w/<expected>` would answer it with a 401.
+ */
+export declare class LinkWorkspaceMismatch extends Error {
+    readonly linked: string;
+    readonly expected: string;
+    constructor(linked: string, expected: string);
+}
 export declare class LinkError extends Error {
     readonly status: number;
     constructor(message: string, status: number);
@@ -58,19 +75,35 @@ export interface LinkOptions {
 }
 /** The control-plane origin of a base URL. */
 export declare function linkOrigin(base: string): string;
+/**
+ * The workspace a base URL addresses — `<slug>` of a `/w/<slug>` path, split
+ * exactly like the server's tenant router — or undefined for a bare origin.
+ */
+export declare function linkWorkspace(base: string): string | undefined;
 /** 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. */
+/**
+ * Ask the server for a link code. `workspace` (normally `linkWorkspace(base)`)
+ * rides the approve and QR URLs as a preselect hint only — the start body
+ * stays `{kind, label}`, because the server refuses unknown fields there.
+ */
 export declare function startLink(base: string, opts: {
     label: string;
+    workspace?: string;
 } & LinkOptions): Promise<LinkStart>;
 export interface PollOptions extends LinkOptions {
     /** Seconds between claims (min 2). */
     interval?: number;
+    /** The workspace the recorder records into; a claim pinned elsewhere rejects with LinkWorkspaceMismatch. */
+    workspace?: string;
     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. */
+/**
+ * Claim until approved. Resolves with the token; throws LinkExpired on 404,
+ * LinkWorkspaceMismatch when approved into another workspace than
+ * `opts.workspace`, AbortError on abort.
+ */
 export declare function pollLink(base: string, deviceCode: string, opts?: PollOptions): Promise<Linked>;
 export {};

package/build/index.js

@@ -7,7 +7,12 @@
  *   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
+ *     → 202 pending · 200 {token, kind, workspace, label, expires_in} · 404 expired
+ *
+ * A base that addresses one workspace (`…/w/<slug>`) carries that slug as a
+ * `workspace=<slug>` hint on the approve and QR URLs (the approve page
+ * preselects it) and refuses a claim pinned to any other workspace — its
+ * token could never authenticate against `/w/<slug>`.
  *
  * Pure TypeScript: no DOM or React Native globals — `fetch` is taken from
  * the options or from globalThis.
@@ -19,6 +24,19 @@ export class LinkExpired extends Error {
         this.name = 'LinkExpired';
     }
 }
+/**
+ * The approver pinned the token to another workspace than the one the
+ * recorder records into. The token is discarded (never returned): every
+ * session door under `/w/<expected>` would answer it with a 401.
+ */
+export class LinkWorkspaceMismatch extends Error {
+    constructor(linked, expected) {
+        super(`linked into ${linked} — this app records into ${expected}; link again and pick ${expected}`);
+        this.linked = linked;
+        this.expected = expected;
+        this.name = 'LinkWorkspaceMismatch';
+    }
+}
 export class LinkError extends Error {
     constructor(message, status) {
         super(message);
@@ -46,6 +64,28 @@ export function permanentStatus(status) {
 export function linkOrigin(base) {
     return new URL(base).origin;
 }
+/**
+ * The workspace a base URL addresses — `<slug>` of a `/w/<slug>` path, split
+ * exactly like the server's tenant router — or undefined for a bare origin.
+ */
+export function linkWorkspace(base) {
+    const m = /^\/w\/([^/]+)/.exec(new URL(base).pathname);
+    if (!m?.[1])
+        return undefined;
+    try {
+        return decodeURIComponent(m[1]);
+    }
+    catch {
+        return m[1];
+    }
+}
+function withWorkspace(url, workspace) {
+    if (!workspace)
+        return url;
+    const u = new URL(url);
+    u.searchParams.set('workspace', workspace);
+    return u.href;
+}
 /** A 401 from a session door: the stored token is dead. */
 export function isUnauthorized(status) {
     return status === 401;
@@ -90,7 +130,11 @@ function requireString(w, key, status) {
         throw new LinkError(`link start → malformed payload (${key})`, status);
     return v;
 }
-/** Ask the server for a link code. */
+/**
+ * Ask the server for a link code. `workspace` (normally `linkWorkspace(base)`)
+ * rides the approve and QR URLs as a preselect hint only — the start body
+ * stays `{kind, label}`, because the server refuses unknown fields there.
+ */
 export async function startLink(base, opts) {
     const origin = linkOrigin(base);
     const res = await fetcher(opts)(`${origin}/api/v1/cli/auth`, {
@@ -122,8 +166,8 @@ export async function startLink(base, opts) {
         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)}`),
+        verifyUrl: withWorkspace(sameOriginUrl(origin, typeof w.verify_url === 'string' ? w.verify_url : undefined, verifyPath, `/cli-auth?code=${encodeURIComponent(userCode)}`), opts.workspace),
+        qrUrl: withWorkspace(sameOriginUrl(origin, qrPath, qrPath, `/cli-auth/qr?code=${encodeURIComponent(userCode)}`), opts.workspace),
         interval: Math.max(2, Number(w.interval) || 2),
         expires_in: Number(w.expires_in) || 0,
     };
@@ -148,7 +192,11 @@ function abortError() {
     e.name = 'AbortError';
     return e;
 }
-/** Claim until approved. Resolves with the token; throws LinkExpired on 404, AbortError on abort. */
+/**
+ * Claim until approved. Resolves with the token; throws LinkExpired on 404,
+ * LinkWorkspaceMismatch when approved into another workspace than
+ * `opts.workspace`, AbortError on abort.
+ */
 export async function pollLink(base, deviceCode, opts = {}) {
     const origin = linkOrigin(base);
     const f = fetcher(opts);
@@ -165,8 +213,17 @@ export async function pollLink(base, deviceCode, opts = {}) {
             body: JSON.stringify({ device_code: deviceCode }),
             signal: opts.signal,
         });
-        if (res.status === 200)
-            return (await res.json());
+        if (res.status === 200) {
+            const linked = (await res.json());
+            // Fail closed: a recorder claim always names its workspace (the server
+            // sets it for kind recorder), so a missing or non-string one is refused
+            // like a foreign one — never stored against a base it cannot serve.
+            if (opts.workspace && linked.workspace !== opts.workspace) {
+                const got = typeof linked.workspace === 'string' && linked.workspace ? linked.workspace : '(no workspace)';
+                throw new LinkWorkspaceMismatch(got, opts.workspace);
+            }
+            return linked;
+        }
         if (res.status === 404 || res.status === 410)
             throw new LinkExpired();
         if (res.status !== 202)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vitrinka/link",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "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": {