@homie-rocks/studio 0.58.1 → 0.58.2

package/CHANGELOG.md

@@ -17,6 +17,21 @@ To bring a studio up to date, tell Claude: "Upgrade my studio to the newest Homi
 `npx -y @homie-rocks/studio@latest upgrade`, which shows what's new since the version your studio pins (from this
 file) and what the upgrade would change, and changes nothing until you agree.
 
+## [0.58.2] - 2026-10-17
+
+**Plugin 0.58.2**
+
+The studio owner opens a private app role. A staff link can expire, and it can be listed or revoked on its own.
+
+### Added
+
+- A signed-in studio owner opens a private app role with the owner session. Everyone else still needs that role's link.
+- `homie-studio app role <id> --list` lists each private role's link and expiry. `--expires` takes a day count (`30d`) or a unix time in milliseconds. `--revoke-link` revokes the link and leaves a player's own grant as it was.
+
+### Upgrade notes
+
+- Upgrade the studio to pick this up. A link issued before this version has no expiry until one is set.
+
 ## [0.58.1] - 2026-10-17
 
 **Plugin 0.58.1**

package/apps/APPS.md

@@ -26,7 +26,7 @@ Use existing netplay events for refresh notices and shared animation. A missed o
 
 ## Staff
 
-`homie-studio app role welcome staff --url <origin>` returns an unpredictable role address for the owner. Add `--player <account-id>` to grant an existing non-guest account, or `--revoke` with that player to remove it. The command reuses the office's short-lived owner key. Accounts/passkeys and the office owner's existing session are reused. An anonymous browser with the link goes to `/account/` to sign in; a signed-in account without a grant receives 403. Every record call rechecks the grant, so revocation applies to open tablets too.
+`homie-studio app role welcome staff --url <origin>` returns an unpredictable role address for the owner. Add `--player <account-id>` to grant an existing non-guest account, or `--revoke` with that player to remove it. `--list` lists each sign-in role's link and expiry. `--revoke-link` deletes that role's link, so the old address answers 404. `--expires <ms>` or `--expires 7d` sets an expiry within 366 days; omit it for a link that does not expire. The command reuses the office's short-lived owner key. A signed-in studio owner opens their own private roles without a link. Accounts/passkeys and the office owner's existing session are reused. An anonymous browser with the link goes to `/account/` to sign in; a signed-in account without a grant receives 403. An expired or revoked link answers 404. Every record call rechecks the grant, so revocation applies to open tablets too.
 
 The private address hides the staff entrance; it is not a bearer permission. It is never in public metadata. Passkeys require HTTPS or localhost. `dev --lan` exposes the local site to the same Wi-Fi, but does not weaken staff authentication. On local HTTP, provision test sessions explicitly in tests or use a secure local origin for real sign-in.
 

package/bin/homie-studio.mjs

@@ -14,7 +14,7 @@
  *                                          extension, Claude Code or any MCP client builds in the same chat that shows
  *                                          the cards (lib/mcp.mjs); --studios: the folder the studios live in
  *   homie-studio app new <id> [--from welcome|gathering|giving|quiz|jobs] [--name "<App Name>"]
- *   homie-studio app role <id> <role> [--player <account>] [--revoke] [--url <site>]
+ *   homie-studio app role <id> [--list] | <id> <role> [--player <account>] [--revoke] [--revoke-link] [--expires <ms|Nd>] [--url <site>]
  *   homie-studio game new <id> [--from gem-rush] [--name "<Game Name>"]
  *   homie-studio games
  *   homie-studio build [<id>] [--maps] [--types] [--long-check] [--quick]   (--maps: also keep each bundle's source map and
@@ -382,7 +382,7 @@ import { standaloneDeployNotes } from '../lib/standalone.mjs';
 const argv = process.argv.slice(2);
 const flags = new Map();
 // build --quick keeps compilation and type checks, skips rules generated play/smoke checks.
-const BOOL_FLAGS = ['webgl-failure', 'quick', 'public', 'lan', 'off', 'revoke', 'json', 'yes', 'detach', 'no-install', 'plan', 'stop', 'share', 'apply', 'diff', 'template', 'ci', 'fresh', 'install', 'remove', 'replace', 'artifact', 'open', 'reopen', 'kids', 'remote-ai', 'dry-run', 'verify', 'maps', 'profile', 'hands-on', 'automatic', 'unlock', 'confirm', 'no-library', 'no-validate', 'rigged', 'no-rig', 'supporter', 'giving', 'managed', 'live', 'manual', 'renew', 'send', 'accept-tos', 'quiet', 'no-local-ai', 'timestamps', 'overwrite', 'own-route', 'before', 'release', 'device'];
+const BOOL_FLAGS = ['webgl-failure', 'quick', 'public', 'lan', 'off', 'revoke', 'revoke-link', 'list', 'json', 'yes', 'detach', 'no-install', 'plan', 'stop', 'share', 'apply', 'diff', 'template', 'ci', 'fresh', 'install', 'remove', 'replace', 'artifact', 'open', 'reopen', 'kids', 'remote-ai', 'dry-run', 'verify', 'maps', 'profile', 'hands-on', 'automatic', 'unlock', 'confirm', 'no-library', 'no-validate', 'rigged', 'no-rig', 'supporter', 'giving', 'managed', 'live', 'manual', 'renew', 'send', 'accept-tos', 'quiet', 'no-local-ai', 'timestamps', 'overwrite', 'own-route', 'before', 'release', 'device'];
 const positional = [];
 for (let i = 0; i < argv.length; i++) {
   const a = argv[i];
@@ -950,8 +950,18 @@ async function main() {
   if (cmd === 'app' && sub === 'role') {
     const { withKey } = await import('../lib/office.mjs');
     const id = positional[2]; const role = positional[3];
-    if (!/^[a-z0-9][a-z0-9-]{0,39}$/.test(id ?? '') || !/^[a-z][a-z0-9-]{0,39}$/.test(role ?? '')) throw new Error('app role <id> <role> [--player <account>] [--revoke] [--url <site>]');
-    return withKey(root, flags.get('url'), (call) => call(`/${id}/api/app/roles`, { role, studio:flags.has('studio'), ...(flags.get('player') ? { player: flags.get('player') } : {}), revoke: flags.has('revoke') }));
+    const usage = 'app role <id> --list | app role <id> <role> [--player <account>] [--revoke] [--revoke-link] [--expires <ms|Nd>] [--url <site>]';
+    if (!/^[a-z0-9][a-z0-9-]{0,39}$/.test(id ?? '')) throw new Error(usage);
+    if (flags.has('list')) return withKey(root, flags.get('url'), (call) => call(`/${id}/api/app/roles`, { list: true }));
+    if (!/^[a-z][a-z0-9-]{0,39}$/.test(role ?? '')) throw new Error(usage);
+    let expires;
+    if (flags.has('expires')) {
+      const raw = String(flags.get('expires') ?? '');
+      const days = /^(\d{1,3})d$/.exec(raw);
+      expires = days ? Date.now() + Number(days[1]) * 86400000 : Number(raw);
+      if (!Number.isSafeInteger(expires) || (days && (Number(days[1]) < 1 || Number(days[1]) > 366))) throw new Error(usage);
+    }
+    return withKey(root, flags.get('url'), (call) => call(`/${id}/api/app/roles`, { role, studio:flags.has('studio'), ...(flags.get('player') ? { player: flags.get('player') } : {}), revoke: flags.has('revoke'), ...(flags.has('revoke-link') ? { revokeLink: true } : {}), ...(expires !== undefined ? { expires } : {}) }));
   }
   if (cmd === 'app' && sub === 'new') return newApp(root, positional[2], { name: flags.get('name'), from: flags.get('from') ?? 'welcome' });
   if (cmd === 'game' && sub === 'new') return newGame(root, positional[2], { from: flags.get('from') ?? 'gem-rush', name: flags.get('name') });

package/guides/app/SKILL.md

@@ -162,7 +162,7 @@ Use `createAppRecords` from `@homie-rocks/studio/apps` for lasting records. Decl
 
 Public collections reach everyone allowed to read them. A ticket number or filtering the HUD is not privacy. Keep personal/private records in a different collection whose read permission excludes customers and walls. Do not put contact details in the starter's public queue.
 
-`homie-studio app role <id> staff --player <account-id> --url <site>` grants an existing signed-in account and returns its private role address. Without `--player` it returns the owner's role address. The existing owner check protects issuance; the link alone grants nothing. `--revoke` removes a named account's grant. Staff use the studio's existing account/passkey sign-in. Keep these links private.
+`homie-studio app role <id> staff --player <account-id> --url <site>` grants an existing signed-in account and returns its private role address. Without `--player` it returns the owner's role address. The existing owner check protects issuance; the link alone grants nothing. `--revoke` removes a named account's grant. `--list` lists links, `--revoke-link` deletes one, and `--expires 7d` (or a unix millisecond time) sets an expiry within 366 days. A signed-in studio owner opens their own private roles without a link. Staff use the studio's existing account/passkey sign-in. Keep these links private.
 
 The complete helper and limits are in `node_modules/@homie-rocks/studio/apps/APPS.md`. Import `appLink`, `qrSvg`, and `randomId` from `@homie-rocks/studio/links` for a ticket URL with parameters. Build customer links from a clean public address, never by copying a staff URL. `randomId` works on plain HTTP.
 

package/lib/template-history.json

@@ -4218,6 +4218,48 @@
      }
     }
    }
+  },
+  "0.58.2": {
+   "files": {
+    "CLAUDE.md": "ddf2b2a0376202f6",
+    "README.md": "684b3cca8001673c",
+    "HANDOFF.md": "29337e2ace95b2e7",
+    "games/README.md": "5ad32fe80c61f117",
+    "music/README.md": "a3dc042dadd39df8",
+    "videos/README.md": "16babc3437d5545b",
+    "posts/README.md": "37841aae476bd540",
+    "site/README.md": "1dbdf22c03a1e505",
+    "site/src/worker.mjs": "6cc5c6131eaf6fd0"
+   },
+   "sections": {
+    "AGENTS.md": {
+     "(intro)": "af7f2f732505d379",
+     "## Version-matched authoring guides": "f6261a0e5801b96b",
+     "## Layout": "f3a280b8c96cd068",
+     "## Apps: one screen, roles and parts": "c10aa0441ea89702",
+     "## Commands (all through the pinned CLI in node_modules)": "c20d90de21cde0c7",
+     "## The site": "0cb8dd9a6f8a0096",
+     "## Making games": "bb715272fd1a615b",
+     "## The Game Codex and progress": "0738ef719cef3a4c",
+     "## Art direction and models": "a48fff7bf0a5f2fc",
+     "## Running live games (the back office)": "51ebf2ab756f6e4d",
+     "## Servers and AI seats": "1ccfd549d2369a60",
+     "## Selling things (the shop)": "0df5a5fe1833c624",
+     "## Continuing a build from the Claude app": "0d68081e924ca419",
+     "## Rules": "b2234d80f6cbe71d",
+     "## Telling Homie": "80b46fdd9e578db8",
+     "## Beta": "9d02638207a26e73"
+    }
+   },
+   "named": {
+    "Homie Arcade": {
+     "sections": {
+      "AGENTS.md": {
+       "## Commands (all through the pinned CLI in node_modules)": "8364e05cebefcba4"
+      }
+     }
+    }
+   }
   }
  }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@homie-rocks/studio",
-  "version": "0.58.1",
+  "version": "0.58.2",
   "description": "A studio for games, music and video on its own Cloudflare: scaffold, multiplayer starters on the netplay contract, a port toolkit that makes existing single-player web games multiplayer, the site Worker with public rooms (Table/Lobby Durable Objects and D1, all on the free Workers plan, no payment method), a site with the hub's sections (Home, Games, Music, Videos, Rooms, Posts with feeds) in the studio's own look, an epic landing page for every game, big songs and videos in the studio's own R2 once it has storage (uploaded, checked by SHA-256, served at the same addresses), deploy, and the homie.rocks directory.",
   "type": "module",
   "license": "Apache-2.0",

package/worker/app-records.mjs

@@ -19,7 +19,7 @@ CREATE TABLE IF NOT EXISTS app_roles (
   PRIMARY KEY (app, role, player)
 );
 CREATE TABLE IF NOT EXISTS app_role_links (
-  app TEXT NOT NULL, role TEXT NOT NULL, token TEXT NOT NULL,
+  app TEXT NOT NULL, role TEXT NOT NULL, token TEXT NOT NULL, expires_at INTEGER,
   PRIMARY KEY (app, role)
 );
 `;
@@ -35,8 +35,37 @@ async function bodyOf(request) {
   for (const chunk of chunks) { bytes.set(chunk, at); at += chunk.length; }
   return JSON.parse(new TextDecoder().decode(bytes) || '{}');
 }
+const ROLE_LINK_YEAR = 366 * 24 * 60 * 60 * 1000;
+const roleLinkReady = new WeakSet();
+/** Old studios have no expires_at. One ALTER per database; a duplicate column is the column already being there. */
+async function ensureRoleLinkExpiry(db) {
+  if (!db || roleLinkReady.has(db)) return true;
+  try {
+    await db.prepare('ALTER TABLE app_role_links ADD COLUMN expires_at INTEGER').run();
+    roleLinkReady.add(db);
+    return true;
+  } catch (error) {
+    if (/duplicate column/i.test(String(error?.message ?? error))) { roleLinkReady.add(db); return true; }
+    return false;
+  }
+}
+async function roleLink(env, app, role) {
+  if (await ensureRoleLinkExpiry(env.DB)) {
+    try { return await env.DB.prepare('SELECT token, expires_at FROM app_role_links WHERE app = ?1 AND role = ?2').bind(app, role).first(); } catch { /* column still absent */ }
+  }
+  const row = await env.DB.prepare('SELECT token FROM app_role_links WHERE app = ?1 AND role = ?2').bind(app, role).first();
+  return row ? { token: row.token, expires_at: null } : null;
+}
+const linkLive = (row) => !!row && (row.expires_at == null || Number(row.expires_at) > Date.now());
+const linkUrl = (url, meta, role, token) => `${url.origin.replace('127.0.0.1', 'localhost')}/${meta.id}/open?role=${role}&access=${token}`;
+function expiryOf(value) {
+  if (value == null) return null;
+  const n = typeof value === 'number' ? value : Number(value);
+  if (!Number.isSafeInteger(n) || n <= Date.now() || n > Date.now() + ROLE_LINK_YEAR) return undefined;
+  return n;
+}
 /** Private links conceal staff addresses; a signed-in grant is still required on every request. */
-export async function appAccess(request, env, meta, url) {
+export async function appAccess(request, env, meta, url, options = {}) {
   const role = appRole(meta, url);
   const declared = Object.hasOwn(meta.roles ?? {}, role) ? meta.roles[role] : null;
   if (!declared) return { ok: false, status: 404, error: 'unknown role' };
@@ -54,8 +83,10 @@ export async function appAccess(request, env, meta, url) {
   }
   const handoff=cookieValues(request,`studio_app_${meta.id}_${role}`)[0];
   if(handoff&&await appAssetTicket(env,meta.id,handoff,{meta,purpose:'handoff',expectedRole:role,launch:launchOf(meta,await settingsOf(env),env)}))return {ok:true,role,can:declared.can};
-  const link = await env.DB.prepare('SELECT token FROM app_role_links WHERE app = ?1 AND role = ?2').bind(meta.id, role).first();
-  if (!link || link.token !== url.searchParams.get('access')) return { ok: false, status: 404, error: 'private role link required' };
+  // Opening the app: the signed-in studio owner needs no link. hasRole passes owner:false so a custom route still requires that role's own link.
+  if (options.owner !== false && await isOwner(request, env)) return { ok: true, role, can: declared.can };
+  const link = await roleLink(env, meta.id, role);
+  if (!linkLive(link) || link.token !== url.searchParams.get('access')) return { ok: false, status: 404, error: 'private role link required' };
   if (await isOwner(request, env)) return { ok: true, role, can: declared.can };
   const person = await players.of(request, env);
   if (!person || person.guest) return { ok: false, status: 401, error: 'sign in to this studio' };
@@ -72,6 +103,17 @@ export async function appRecordsRoute(request, env, meta, url, sub) {
       if (request.method !== 'POST') return fail(405, 'POST required');
       if (!key && !sameOrigin(request, url)) return fail(403, 'same origin required');
       const b = await bodyOf(request);
+      await ensureRoleLinkExpiry(env.DB);
+      if (b.list === true) {
+        const roles = [];
+        for (const [role, declared] of Object.entries(meta.roles ?? {})) {
+          if (!declared?.signIn) continue;
+          const row = await roleLink(env, meta.id, role);
+          const live = linkLive(row);
+          roles.push({ role, expiresAt: row?.expires_at == null ? null : Number(row.expires_at), link: live ? linkUrl(url, meta, role, row.token) : null });
+        }
+        return json({ ok: true, roles });
+      }
       if (!Object.hasOwn(meta.roles, b.role) || !meta.roles[b.role].signIn) return fail(400, 'name a sign-in role');
       if (b.player !== undefined) {
         if (!ID.test(b.player)) return fail(400, 'invalid account');
@@ -79,11 +121,21 @@ export async function appRecordsRoute(request, env, meta, url, sub) {
         if (!p || p.guest) return fail(400, 'role grants require an existing signed-in account');
         await env.DB.prepare(b.revoke === true ? 'DELETE FROM app_roles WHERE app = ?1 AND role = ?2 AND player = ?3' : 'INSERT OR IGNORE INTO app_roles (app, role, player) VALUES (?1, ?2, ?3)').bind(b.studio === true ? '*' : meta.id, b.role, b.player).run();
       }
+      if (b.revokeLink === true) {
+        await env.DB.prepare('DELETE FROM app_role_links WHERE app = ?1 AND role = ?2').bind(meta.id, b.role).run();
+        return json({ ok: true, role: b.role, revoked: true });
+      }
+      let expires;
+      if (Object.hasOwn(b, 'expires')) {
+        expires = expiryOf(b.expires);
+        if (expires === undefined) return fail(400, 'expiry must be a future time within 366 days');
+      }
       const token = crypto.randomUUID().replaceAll('-', '');
       if (b.rotate === true) await env.DB.prepare('DELETE FROM app_role_links WHERE app = ?1 AND role = ?2').bind(meta.id, b.role).run();
       await env.DB.prepare('INSERT OR IGNORE INTO app_role_links (app, role, token) VALUES (?1, ?2, ?3)').bind(meta.id, b.role, token).run();
-      const row = await env.DB.prepare('SELECT token FROM app_role_links WHERE app = ?1 AND role = ?2').bind(meta.id, b.role).first();
-      return json({ ok: true, link: `${url.origin.replace('127.0.0.1','localhost')}/${meta.id}/open?role=${b.role}&access=${row.token}`, role: b.role });
+      if (expires !== undefined) await env.DB.prepare('UPDATE app_role_links SET expires_at = ?3 WHERE app = ?1 AND role = ?2').bind(meta.id, b.role, expires).run();
+      const row = await roleLink(env, meta.id, b.role);
+      return json({ ok: true, link: linkUrl(url, meta, b.role, row.token), role: b.role, expiresAt: row.expires_at == null ? null : Number(row.expires_at) });
     }
     const match = /^api\/app\/records\/([a-z][a-z0-9-]{0,39})(?:\/([A-Za-z0-9_-]{1,64}))?$/.exec(sub);
     if(!match && /^api\/app\/records\/[^/]+\//.test(sub))return fail(400,'record id: 1–64 letters, digits, underscore or hyphen');

package/worker/build-id.mjs

@@ -1,2 +1,2 @@
 // Generated by lib/build-identity.mjs; identifies the bundled runtime sources.
-export const STUDIO_BUILD = Object.freeze({"version":"0.58.1","sha256":"b3944d94ae64b4e7755614a9801c54216f14fcb741e9598bd5c4eab117deae50"});
+export const STUDIO_BUILD = Object.freeze({"version":"0.58.2","sha256":"5186ba06317a7de1677209dbbba72ee69d4e1cf79a08b46c74e9c20bd92e74a7"});

package/worker/route-auth.mjs

@@ -13,7 +13,7 @@ export async function hasRole(request, env, app, role) {
   const launch = launchOf(meta, await settingsOf(env, {fresh:true}), env);
   if (launch !== 'public' && !(await accessOf(request, env, app, launch)).ok) return false;
   url.searchParams.set('role', role);
-  return (await (await import('./app-records.mjs')).appAccess(request, env, meta, url)).ok === true;
+  return (await (await import('./app-records.mjs')).appAccess(request, env, meta, url, { owner: false })).ok === true;
 }
 
 /** Return a refusal response, or null when the browser supplied same-origin evidence. */

package/worker/version.mjs

@@ -1,2 +1,2 @@
 /** The @homie-rocks/studio version this Worker code is (package.json's; a test keeps them equal). Cache-busts /_homie/site.js. */
-export const STUDIO_VERSION_TAG = '0.58.1';
+export const STUDIO_VERSION_TAG = '0.58.2';