@volter/teams 0.1.0

package/server/machine-link.mjs

@@ -0,0 +1,228 @@
+// Machine doors through the server (design §11).
+//
+//   GET  /api/v1/teams/{team}/machines/{id}/link     the machine's one outbound link
+//   GET  /api/v1/teams/{team}/machines/{id}/channel  a caller's channel to that machine
+//   /machines/{id}/access[/{grant}]                  machine grants: list, issue, revoke
+//
+// A caller's channel is the machine channel (`../channel.mjs`) terminated here.
+// Every stream the caller opens is re-opened on the machine's link carrying a
+// claim, { principal, groups, custodian | grants }, recomputed from the store at
+// that moment; the machine re-derives the admission from its own synced copy
+// of the grants and checks each door against it. A caller with no grant on a
+// machine is refused exactly as a machine that does not exist is.
+import { Channel } from '../channel.mjs';
+import { bearer } from './auth.mjs';
+
+const LINK_PROTOCOL = 'supercode-machine-link.v1';
+const CHANNEL_PROTOCOL = 'supercode-machine-channel.v1';
+/** The machine daemon's door vocabulary: operate (operator: harness.v1 and launch) and the participant caps its doors check. */
+const CAPS = new Set(['operate', 'view', 'observe', 'interact', 'control', 'files', 'ports']);
+// A target is `*` or `<kind>:<name>`. The server checks shape only: which kinds a machine
+// serves is the daemon's business, and a grant on a kind it does not serve covers nothing.
+const TARGET = /^(\*|root:(\*|\/[^\x00-\x1f]{0,4095})|(?!root:)[a-z][a-z0-9-]{0,31}:[^\x00-\x1f]{1,4096})$/;
+// `*` is the whole machine: operate it, or list it. Anything more names the kind it reaches.
+const WHOLE_MACHINE_CAPS = new Set(['operate', 'view']);
+const MAX_GRANT_MS = 90 * 24 * 60 * 60 * 1000;
+
+const links = (api) => api.machineLinks ??= new Map();
+const channels = (api) => api.machineChannels ??= new Set();
+const key = (teamId, machineId) => `${teamId}\0${machineId}`;
+const grantJson = (row) => ({ id: row.id, machine_id: row.machine_id, subject_id: row.subject_id, caps: JSON.parse(row.caps_json), targets: JSON.parse(row.targets_json), issuer_id: row.issuer_id, created_at: row.created_at, expires_at: row.expires_at, revision: row.revision });
+
+/** The unexpired grants of one machine, as its configuration carries them to the machine. */
+export async function machineGrantRows(api, teamId, machineId) {
+  const rows = await api.store.query('SELECT * FROM machine_grants WHERE team_id=? AND machine_id=? AND expires_at>? ORDER BY id', [teamId, machineId, api.clock.nowMs()]);
+  return rows.map(grantJson);
+}
+
+/** What the caller may claim on the machine right now, or null (indistinguishable from no machine). */
+async function claimFor(api, auth, machineId) {
+  const machine = await api.store.one('SELECT custodian_id FROM machines WHERE team_id=? AND id=? AND revoked_at IS NULL', [auth.team_id, machineId]);
+  if (!machine) return null;
+  const membership = await api.store.one('SELECT active FROM memberships WHERE team_id=? AND principal_id=?', [auth.team_id, auth.principal_id]);
+  if (!membership?.active) return null;
+  const groups = auth.group_ids ?? [];
+  if (machine.custodian_id === auth.principal_id) return { principal: auth.principal_id, groups, custodian: true };
+  const subjects = [auth.principal_id, ...groups];
+  const rows = await api.store.query(`SELECT id, revision FROM machine_grants WHERE team_id=? AND machine_id=? AND expires_at>? AND subject_id IN (${subjects.map(() => '?').join(',')}) ORDER BY id`, [auth.team_id, machineId, api.clock.nowMs(), ...subjects]);
+  if (!rows.length) return null;
+  // Revisions let the machine notice a grant it holds has changed (rewritten, narrowed) and resync.
+  return { principal: auth.principal_id, groups, grants: rows.map((row) => row.id), revisions: Object.fromEntries(rows.map((row) => [row.id, row.revision])) };
+}
+
+/** Close every channel a member leaving the team, or a group losing a member or being deleted, leaves without its claimed authority. */
+export function closeChannelsFor(api, teamId, { principalId = null, groupId = null, reason = 'access_revoked' } = {}) {
+  let closed = 0;
+  for (const entry of channels(api)) {
+    if (entry.teamId !== teamId) continue;
+    const claim = entry.claim ?? {};
+    const hit = groupId ? (claim.groups ?? []).includes(groupId) && (!principalId || entry.principal === principalId) : entry.principal === principalId;
+    if (!hit) continue;
+    entry.close(reason);
+    closed += 1;
+  }
+  return closed;
+}
+
+/** Close the channels a revocation or machine removal leaves without authority; the next stream would be refused anyway. */
+export function closeMachineChannels(api, teamId, machineId, { grantId = null, reason = 'access_revoked' } = {}) {
+  let closed = 0;
+  for (const entry of channels(api)) {
+    if (entry.teamId !== teamId || entry.machineId !== machineId) continue;
+    if (grantId && !entry.claim?.grants?.includes(grantId)) continue;
+    entry.close(reason);
+    closed += 1;
+  }
+  if (!grantId) links(api).get(key(teamId, machineId))?.close(reason);
+  return closed;
+}
+
+export async function machineGrantRoute({ api, req, res, auth, machineId, grantId, url, requestId, parseJson, exact, fail, send, result, guardedMutation, requireRevision }) {
+  if (!['user', 'service'].includes(auth.kind)) fail(403, 'forbidden', 'user or service credential required');
+  const machine = await api.store.one('SELECT * FROM machines WHERE team_id=? AND id=? AND revoked_at IS NULL', [auth.team_id, machineId]);
+  const admin = auth.active && (auth.role === 'owner' || auth.role === 'admin');
+  // Team roles grant no execution authority: only the machine's custodian, or an admin, issues its grants.
+  if (!machine || (machine.custodian_id !== auth.principal_id && !admin)) fail(404, 'not_found', 'machine not found');
+  const context = { server_id: api.serverId, team_id: auth.team_id, principal_id: auth.principal_id };
+  if (req.method === 'GET') {
+    if (grantId) {
+      const row = await api.store.one('SELECT * FROM machine_grants WHERE team_id=? AND machine_id=? AND id=?', [auth.team_id, machineId, grantId]);
+      if (!row) fail(404, 'not_found', 'grant not found');
+      return send(res, 200, result(api, auth, grantJson(row)), requestId, { ETag: `"${row.revision}"` });
+    }
+    if ([...url.searchParams].length) fail(400, 'invalid_request', 'machine grants take no query parameters');
+    return send(res, 200, { version: 1, context, items: await machineGrantRows(api, auth.team_id, machineId), next_cursor: null }, requestId);
+  }
+  if (req.method === 'POST' && !grantId) {
+    const body = await parseJson(req); exact(body, ['subject_id', 'caps', 'targets', 'expires_at']);
+    if (!Array.isArray(body.caps) || !body.caps.length || new Set(body.caps).size !== body.caps.length || !body.caps.every((cap) => CAPS.has(cap))) fail(400, 'invalid_request', `caps must be a non-empty set of ${[...CAPS].join(', ')}`);
+    if (!Array.isArray(body.targets) || !body.targets.length || body.targets.length > 64 || !body.targets.every((target) => typeof target === 'string' && TARGET.test(target))) fail(400, 'invalid_request', 'targets must name * or <kind>:<name> (for example pane:<key>, root:/path, port:<pane>/<n>, pane:*)');
+    if (body.caps.includes('operate') && !(body.targets.length === 1 && body.targets[0] === '*')) fail(400, 'invalid_request', 'operate is the whole machine: its only target is *');
+    if (body.targets.includes('*') && !body.caps.every((cap) => WHOLE_MACHINE_CAPS.has(cap))) fail(400, 'invalid_request', 'only operate and view may target *; name the kind instead (e.g. pane:*, port:*)');
+    const now = api.clock.nowMs();
+    if (!Number.isSafeInteger(body.expires_at) || body.expires_at <= now || body.expires_at > now + MAX_GRANT_MS) fail(400, 'invalid_request', 'machine grant expiry must be within 90 days');
+    const subject = typeof body.subject_id === 'string' ? await api.store.one(`SELECT 'member' kind FROM memberships WHERE team_id=? AND principal_id=? AND active=1 UNION ALL SELECT 'group' kind FROM groups_table WHERE team_id=? AND id=?`, [auth.team_id, body.subject_id, auth.team_id, body.subject_id]) : null;
+    if (!subject) fail(400, 'invalid_request', 'subject must be an active member, service account or group of this team');
+    const id = api.ids.next('grant');
+    const row = { id, machine_id: machineId, subject_id: body.subject_id, caps: body.caps, targets: body.targets, issuer_id: auth.principal_id, created_at: now, expires_at: body.expires_at, revision: 1 };
+    const response = result(api, auth, row);
+    await guardedMutation(api, res, auth, [{ sql: 'SELECT 1 ok FROM machines WHERE team_id=? AND id=? AND revoked_at IS NULL', params: [auth.team_id, machineId], code: 'not_found', status: 404, message: 'machine not found' }], [
+      { sql: 'INSERT INTO machine_grants(team_id,id,machine_id,subject_id,caps_json,targets_json,issuer_id,created_at,expires_at) VALUES (?,?,?,?,?,?,?,?,?)', params: [auth.team_id, id, machineId, body.subject_id, JSON.stringify(body.caps), JSON.stringify(body.targets), auth.principal_id, now, body.expires_at] },
+    ], { status: 201, body: response, targetId: id });
+    return send(res, 201, response, requestId, { ETag: '"1"' });
+  }
+  if (req.method === 'DELETE' && grantId) {
+    const row = await api.store.one('SELECT * FROM machine_grants WHERE team_id=? AND machine_id=? AND id=?', [auth.team_id, machineId, grantId]);
+    if (!row) fail(404, 'not_found', 'grant not found');
+    requireRevision(req, row.revision, 'machine grant');
+    await guardedMutation(api, res, auth, [{ sql: 'SELECT 1 ok FROM machine_grants WHERE team_id=? AND id=? AND revision=?', params: [auth.team_id, grantId, row.revision], code: 'revision_mismatch', status: 409, message: 'machine grant revision changed' }], [
+      { sql: 'DELETE FROM machine_grants WHERE team_id=? AND id=?', params: [auth.team_id, grantId] },
+    ], { status: 204, body: null, targetId: grantId });
+    closeMachineChannels(api, auth.team_id, machineId, { grantId });
+    return send(res, 204, null, requestId);
+  }
+  fail(405, 'not_found', 'method not allowed');
+}
+
+/**
+ * Decide an upgrade to one of the two machine sockets from its path and bearer, before any
+ * WebSocket exists. Returns { status, code, message } to refuse, or { door, teamId, machineId, auth }.
+ */
+export async function authorizeMachineUpgrade(api, { authenticate, url, headers }) {
+  if (api.publicOrigin && headers.host !== new URL(api.publicOrigin).host) return { status: 400, code: 'invalid_request', message: 'request Host does not match configured public origin' };
+  const match = /^\/api\/v1\/teams\/([^/]+)\/machines\/([^/]+)\/(link|channel)$/.exec(new URL(url, 'http://local').pathname);
+  if (!match) return { status: 404, code: 'not_found', message: 'not found' };
+  const [, teamId, machineId, door] = match;
+  const auth = await authenticate(api, bearerFrom(headers));
+  if (!auth) return { status: 401, code: 'authentication_required', message: 'authentication required' };
+  if (door === 'link') {
+    if (auth.kind !== 'machine' || auth.team_id !== teamId || auth.machine_id !== machineId) return { status: 403, code: 'forbidden', message: 'exact machine credential required' };
+    const machine = await api.store.one('SELECT incarnation_id FROM machines WHERE team_id=? AND id=? AND revoked_at IS NULL', [teamId, machineId]);
+    if (!machine) return { status: 404, code: 'not_found', message: 'not found' };
+    return { door, teamId, machineId, auth };
+  }
+  if (!['user', 'service'].includes(auth.kind)) return { status: 403, code: 'forbidden', message: 'user or service credential required' };
+  if (auth.team_id === null && auth.kind === 'user') {
+    const membership = await api.store.one('SELECT role,active FROM memberships WHERE team_id=? AND principal_id=?', [teamId, auth.principal_id]);
+    if (!membership?.active) return { status: 401, code: 'authentication_required', message: 'authentication required' };
+    Object.assign(auth, { team_id: teamId, role: membership.role, active: membership.active, group_ids: (await api.store.query('SELECT group_id FROM group_members WHERE team_id=? AND principal_id=?', [teamId, auth.principal_id])).map((row) => row.group_id) });
+  } else if (auth.team_id !== teamId || !auth.active) return { status: 401, code: 'authentication_required', message: 'authentication required' };
+  if (!await claimFor(api, auth, machineId)) return { status: 404, code: 'not_found', message: 'machine not found' };
+  return { door, teamId, machineId, auth };
+}
+
+/**
+ * A caller's bearer: the Authorization header, or, for a browser (which cannot set headers on
+ * a WebSocket), a `bearer.<token>` entry in Sec-WebSocket-Protocol beside the door's protocol.
+ */
+function bearerFrom(headers) {
+  const header = bearer(headers.authorization);
+  if (header) return header;
+  const offered = String(headers['sec-websocket-protocol'] ?? '').split(',').map((value) => value.trim());
+  const entry = offered.find((value) => value.startsWith('bearer.'));
+  return entry ? entry.slice('bearer.'.length) : null;
+}
+
+/** Hand an accepted socket, as a duplex byte stream, to its door. `close(reason)` ends the socket. */
+export function acceptMachineSocket(api, decision, duplex, close) {
+  if (decision.door === 'link') return acceptLink(api, decision.teamId, decision.machineId, duplex, close);
+  return acceptChannel(api, decision.auth, decision.machineId, duplex, close);
+}
+
+export { LINK_PROTOCOL, CHANNEL_PROTOCOL };
+
+/** The machine dialled in: its link replaces any older one for the same machine. */
+async function acceptLink(api, teamId, machineId, duplex, closeSocket) {
+  let channel;
+  try {
+    channel = await Channel.accept(duplex, { floor: 2 });
+  } catch { closeSocket('refused'); return; }
+  const id = key(teamId, machineId);
+  const previous = links(api).get(id);
+  const link = { channel, close: (reason) => closeSocket(reason) };
+  links(api).set(id, link);
+  previous?.close('replaced');
+  channel.on('error', () => {});
+  channel.on('close', () => {
+    if (links(api).get(id) === link) links(api).delete(id);
+    // A caller's open streams ride this link; they end with it, and the caller reopens.
+    for (const entry of channels(api)) if (entry.teamId === teamId && entry.machineId === machineId) entry.dropStreams('machine_offline');
+  });
+}
+
+/** A caller's channel: each stream it opens is forwarded to the machine with a fresh claim. */
+async function acceptChannel(api, auth, machineId, duplex, closeSocket) {
+  let channel;
+  try {
+    channel = await Channel.accept(duplex, { floor: 2 });
+  } catch { closeSocket('refused'); return; }
+  const open = new Set();
+  const entry = {
+    teamId: auth.team_id, machineId, principal: auth.principal_id, claim: null,
+    close: (reason) => closeSocket(reason),
+    dropStreams: (reason) => { for (const pair of open) pair.close(reason); },
+  };
+  channels(api).add(entry);
+  channel.on('error', () => {});
+  channel.on('close', () => { channels(api).delete(entry); entry.dropStreams('caller closed'); });
+  channel.on('stream', async (stream, accept, refuse) => {
+    const claim = await claimFor(api, auth, machineId).catch(() => null);
+    if (!claim) return refuse('no machine grant for this caller');
+    entry.claim = claim;
+    const link = links(api).get(key(auth.team_id, machineId));
+    if (!link) return refuse('machine_offline: the machine is not linked to this server');
+    let upstream;
+    try {
+      upstream = await link.channel.open(stream.name, { ...(stream.params ?? {}), _admitted: claim });
+    } catch (error) {
+      return refuse(error.message.replace(/^[a-z]+ refused: /, ''));
+    }
+    accept();
+    const pair = { close: (reason) => { if (!stream.closed) stream.close(reason); if (!upstream.closed) upstream.close(reason); } };
+    open.add(pair);
+    stream.on('data', (data) => { if (!upstream.closed) upstream.write(data); });
+    upstream.on('data', (data) => { if (!stream.closed) stream.write(data); });
+    stream.on('close', (reason) => { open.delete(pair); if (!upstream.closed) upstream.close(reason); });
+    upstream.on('close', (reason) => { open.delete(pair); if (!stream.closed) stream.close(reason); });
+  });
+}

package/server/migrations/001.mjs

@@ -0,0 +1,298 @@
+// Schema migration 001 (SQLite DDL), applied in order by store-core migrate().
+export default `-- Normative schema 1. Apply PRAGMAs first, then DDL/user_version in one migration transaction.
+-- No plaintext credentials, native machine paths, or artifact bytes in audit/event payloads.
+PRAGMA foreign_keys = ON;
+PRAGMA journal_mode = WAL;
+PRAGMA synchronous = FULL;
+PRAGMA busy_timeout = 5000;
+
+CREATE TABLE server_meta (key TEXT PRIMARY KEY, value TEXT NOT NULL) STRICT;
+CREATE TABLE principals (
+  id TEXT PRIMARY KEY, kind TEXT NOT NULL CHECK(kind IN ('user','service')),
+  display_name TEXT NOT NULL
+) STRICT;
+CREATE TABLE teams (
+  id TEXT PRIMARY KEY, name TEXT NOT NULL UNIQUE, revision INTEGER NOT NULL DEFAULT 1,
+  auth_epoch INTEGER NOT NULL DEFAULT 1, journal_revision INTEGER NOT NULL DEFAULT 0,
+  CHECK(revision >= 1 AND auth_epoch >= 1 AND journal_revision >= 0)
+) STRICT;
+CREATE TABLE memberships (
+  team_id TEXT NOT NULL REFERENCES teams(id), principal_id TEXT NOT NULL REFERENCES principals(id),
+  role TEXT NOT NULL CHECK(role IN ('owner','admin','member','viewer')),
+  active INTEGER NOT NULL DEFAULT 1 CHECK(active IN (0,1)), revision INTEGER NOT NULL DEFAULT 1,
+  PRIMARY KEY(team_id,principal_id)
+) STRICT;
+CREATE TABLE groups_table (
+  team_id TEXT NOT NULL REFERENCES teams(id), id TEXT NOT NULL, name TEXT NOT NULL,
+  revision INTEGER NOT NULL DEFAULT 1, PRIMARY KEY(team_id,id), UNIQUE(team_id,name)
+) STRICT;
+CREATE TABLE group_members (
+  team_id TEXT NOT NULL, group_id TEXT NOT NULL, principal_id TEXT NOT NULL,
+  PRIMARY KEY(team_id,group_id,principal_id),
+  FOREIGN KEY(team_id,group_id) REFERENCES groups_table(team_id,id),
+  FOREIGN KEY(team_id,principal_id) REFERENCES memberships(team_id,principal_id)
+) STRICT;
+CREATE TABLE invitations (
+  team_id TEXT NOT NULL REFERENCES teams(id), id TEXT PRIMARY KEY,
+  principal_id TEXT NOT NULL REFERENCES principals(id), secret_hash TEXT NOT NULL UNIQUE,
+  role TEXT NOT NULL CHECK(role IN ('admin','member','viewer')), expires_at INTEGER NOT NULL,
+  consumed_at INTEGER, revoked_at INTEGER
+) STRICT;
+CREATE TABLE machines (
+  team_id TEXT NOT NULL, id TEXT NOT NULL, name TEXT NOT NULL, custodian_id TEXT NOT NULL,
+  enrollment_key TEXT NOT NULL, revoked_at INTEGER, last_seen_at INTEGER,
+  incarnation_id TEXT, heartbeat_sequence INTEGER NOT NULL DEFAULT 0, revision INTEGER NOT NULL DEFAULT 1,
+  PRIMARY KEY(team_id,id), UNIQUE(team_id,custodian_id,enrollment_key),
+  FOREIGN KEY(team_id,custodian_id) REFERENCES memberships(team_id,principal_id)
+) STRICT;
+CREATE TABLE sources (
+  team_id TEXT NOT NULL, id TEXT NOT NULL, name TEXT NOT NULL,
+  kind TEXT NOT NULL CHECK(kind IN ('connector','otlp')), machine_id TEXT, custodian_id TEXT NOT NULL,
+  visibility TEXT NOT NULL CHECK(visibility IN ('team','restricted')),
+  state TEXT NOT NULL CHECK(state IN ('active','paused','revoked')), revision INTEGER NOT NULL DEFAULT 1,
+  last_received_at INTEGER, decoder TEXT, counters_json TEXT NOT NULL DEFAULT '{}', last_error TEXT,
+  PRIMARY KEY(team_id,id), UNIQUE(team_id,name),
+  FOREIGN KEY(team_id,custodian_id) REFERENCES memberships(team_id,principal_id),
+  FOREIGN KEY(team_id,machine_id) REFERENCES machines(team_id,id), CHECK(json_valid(counters_json))
+) STRICT;
+CREATE TABLE machine_roots (
+  team_id TEXT NOT NULL, machine_id TEXT NOT NULL, id TEXT NOT NULL,
+  value_json TEXT NOT NULL CHECK(json_valid(value_json)),
+  PRIMARY KEY(team_id,id), FOREIGN KEY(team_id,machine_id) REFERENCES machines(team_id,id)
+) STRICT;
+CREATE TABLE credentials (
+  id TEXT PRIMARY KEY, token_hash TEXT NOT NULL UNIQUE, principal_id TEXT NOT NULL REFERENCES principals(id),
+  kind TEXT NOT NULL CHECK(kind IN ('user','service','machine','ingest')),
+  team_id TEXT REFERENCES teams(id), source_id TEXT, machine_id TEXT,
+  expires_at INTEGER, revoked_at INTEGER, created_at INTEGER NOT NULL,
+  FOREIGN KEY(team_id,source_id) REFERENCES sources(team_id,id),
+  FOREIGN KEY(team_id,machine_id) REFERENCES machines(team_id,id),
+  CHECK(kind NOT IN ('machine','ingest') OR (team_id IS NOT NULL AND source_id IS NOT NULL)),
+  CHECK(kind != 'machine' OR machine_id IS NOT NULL)
+) STRICT;
+CREATE TABLE sync_rules (
+  team_id TEXT NOT NULL, id TEXT NOT NULL, source_id TEXT NOT NULL, machine_id TEXT NOT NULL,
+  selector_json TEXT NOT NULL, visibility TEXT NOT NULL CHECK(visibility IN ('team','restricted')),
+  backfill_json TEXT NOT NULL, state TEXT NOT NULL CHECK(state IN ('active','paused','removed')),
+  capture_after INTEGER NOT NULL, revision INTEGER NOT NULL DEFAULT 1,
+  PRIMARY KEY(team_id,id), FOREIGN KEY(team_id,source_id) REFERENCES sources(team_id,id),
+  FOREIGN KEY(team_id,machine_id) REFERENCES machines(team_id,id),
+  CHECK(json_valid(selector_json) AND json_valid(backfill_json))
+) STRICT;
+CREATE TABLE sessions (
+  team_id TEXT NOT NULL REFERENCES teams(id), id TEXT NOT NULL, harness TEXT NOT NULL,
+  custodian_id TEXT NOT NULL, visibility TEXT NOT NULL CHECK(visibility IN ('team','restricted')),
+  revision INTEGER NOT NULL DEFAULT 0, access_revision INTEGER NOT NULL DEFAULT 1,
+  created_at INTEGER NOT NULL, deleted_at INTEGER, canonical_id TEXT,
+  PRIMARY KEY(team_id,id), FOREIGN KEY(team_id,custodian_id) REFERENCES memberships(team_id,principal_id),
+  FOREIGN KEY(team_id,canonical_id) REFERENCES sessions(team_id,id)
+) STRICT;
+CREATE TABLE session_grants (
+  team_id TEXT NOT NULL, id TEXT NOT NULL, session_id TEXT NOT NULL,
+  subject_kind TEXT NOT NULL CHECK(subject_kind IN ('principal','group')), subject_id TEXT NOT NULL,
+  role TEXT NOT NULL CHECK(role IN ('reader','manager')), expires_at INTEGER,
+  PRIMARY KEY(team_id,id), FOREIGN KEY(team_id,session_id) REFERENCES sessions(team_id,id),
+  UNIQUE(team_id,session_id,subject_kind,subject_id)
+) STRICT;
+CREATE TABLE origins (
+  team_id TEXT NOT NULL, source_id TEXT NOT NULL, harness TEXT NOT NULL, native_id TEXT NOT NULL,
+  session_id TEXT NOT NULL, generation INTEGER NOT NULL DEFAULT 0, sequence INTEGER NOT NULL DEFAULT 0,
+  digest TEXT, deleted_at INTEGER,
+  PRIMARY KEY(team_id,source_id,harness,native_id),
+  FOREIGN KEY(team_id,source_id) REFERENCES sources(team_id,id),
+  FOREIGN KEY(team_id,session_id) REFERENCES sessions(team_id,id)
+) STRICT;
+CREATE TABLE captures (
+  team_id TEXT NOT NULL, id TEXT NOT NULL, source_id TEXT NOT NULL, harness TEXT NOT NULL,
+  native_id TEXT NOT NULL, generation INTEGER NOT NULL, sequence INTEGER NOT NULL,
+  previous_digest TEXT, state TEXT NOT NULL CHECK(state IN ('staging','committed','aborted')),
+  begin_json TEXT NOT NULL, commit_json TEXT, receipt_json TEXT, created_at INTEGER NOT NULL,
+  PRIMARY KEY(team_id,id), UNIQUE(team_id,source_id,harness,native_id,generation,sequence),
+  FOREIGN KEY(team_id,source_id) REFERENCES sources(team_id,id),
+  CHECK(json_valid(begin_json)), CHECK(commit_json IS NULL OR json_valid(commit_json)),
+  CHECK(receipt_json IS NULL OR json_valid(receipt_json))
+) STRICT;
+CREATE TABLE capture_parts (
+  team_id TEXT NOT NULL, capture_id TEXT NOT NULL, part_index INTEGER NOT NULL CHECK(part_index >= 0),
+  digest TEXT NOT NULL, payload_json TEXT NOT NULL CHECK(json_valid(payload_json)),
+  PRIMARY KEY(team_id,capture_id,part_index),
+  FOREIGN KEY(team_id,capture_id) REFERENCES captures(team_id,id) ON DELETE CASCADE
+) STRICT;
+CREATE TABLE capture_expiries (
+  team_id TEXT NOT NULL, source_id TEXT NOT NULL, id TEXT NOT NULL, expired_at INTEGER NOT NULL,
+  PRIMARY KEY(team_id,id), FOREIGN KEY(team_id,source_id) REFERENCES sources(team_id,id)
+) STRICT;
+CREATE TABLE uploads (
+  team_id TEXT NOT NULL, id TEXT NOT NULL, source_id TEXT NOT NULL,
+  manifest_json TEXT, created_at INTEGER NOT NULL, committed INTEGER NOT NULL DEFAULT 0 CHECK(committed IN (0,1)),
+  PRIMARY KEY(team_id,id), FOREIGN KEY(team_id,source_id) REFERENCES sources(team_id,id),
+  CHECK(manifest_json IS NULL OR json_valid(manifest_json))
+) STRICT;
+CREATE TABLE artifact_chunks (
+  team_id TEXT NOT NULL, upload_id TEXT NOT NULL, chunk_index INTEGER NOT NULL CHECK(chunk_index >= 0),
+  sha256 TEXT NOT NULL, bytes BLOB NOT NULL,
+  PRIMARY KEY(team_id,upload_id,chunk_index),
+  FOREIGN KEY(team_id,upload_id) REFERENCES uploads(team_id,id) ON DELETE CASCADE,
+  CHECK(length(bytes) <= 1048576)
+) STRICT;
+CREATE TABLE session_artifacts (
+  team_id TEXT NOT NULL, session_id TEXT NOT NULL, revision INTEGER NOT NULL,
+  bundle_id TEXT NOT NULL, upload_id TEXT NOT NULL, format TEXT NOT NULL,
+  provenance TEXT NOT NULL CHECK(provenance IN ('capture','export')),
+  file_role TEXT NOT NULL CHECK(file_role IN ('primary','subagent','bundle','source_recovery')),
+  fidelity TEXT NOT NULL CHECK(fidelity IN ('byte_lossless','value_lossless','semantic')),
+  residue_json TEXT NOT NULL CHECK(json_valid(residue_json)),
+  PRIMARY KEY(team_id,session_id,revision,bundle_id,upload_id),
+  FOREIGN KEY(team_id,session_id,revision) REFERENCES session_versions(team_id,session_id,revision) ON DELETE CASCADE,
+  FOREIGN KEY(team_id,upload_id) REFERENCES uploads(team_id,id)
+) STRICT;
+CREATE INDEX session_artifacts_bundle ON session_artifacts(team_id,session_id,revision,provenance,bundle_id);
+CREATE TABLE session_versions (
+  team_id TEXT NOT NULL, session_id TEXT NOT NULL, revision INTEGER NOT NULL,
+  descriptor_json TEXT NOT NULL CHECK(json_valid(descriptor_json)),
+  source_projection_json TEXT NOT NULL CHECK(json_valid(source_projection_json)),
+  search_title TEXT NOT NULL, sort_at INTEGER NOT NULL, created_at INTEGER NOT NULL,
+  PRIMARY KEY(team_id,session_id,revision),
+  FOREIGN KEY(team_id,session_id) REFERENCES sessions(team_id,id)
+) STRICT;
+CREATE TABLE messages (
+  team_id TEXT NOT NULL, session_id TEXT NOT NULL, revision INTEGER NOT NULL,
+  ordinal INTEGER NOT NULL CHECK(ordinal >= 0), id TEXT NOT NULL, source_id TEXT NOT NULL,
+  native_key TEXT NOT NULL, recorded_at INTEGER, value_json TEXT NOT NULL CHECK(json_valid(value_json)),
+  search_text TEXT NOT NULL,
+  PRIMARY KEY(team_id,session_id,revision,ordinal), UNIQUE(team_id,session_id,revision,id),
+  FOREIGN KEY(team_id,session_id,revision) REFERENCES session_versions(team_id,session_id,revision) ON DELETE CASCADE,
+  FOREIGN KEY(team_id,source_id) REFERENCES sources(team_id,id)
+) STRICT;
+CREATE TABLE message_ids (
+  team_id TEXT NOT NULL, source_id TEXT NOT NULL, harness TEXT NOT NULL, native_id TEXT NOT NULL,
+  native_key TEXT NOT NULL, id TEXT NOT NULL,
+  PRIMARY KEY(team_id,source_id,harness,native_id,native_key), UNIQUE(team_id,id),
+  FOREIGN KEY(team_id,source_id) REFERENCES sources(team_id,id)
+) STRICT;
+CREATE TABLE journal (
+  team_id TEXT NOT NULL REFERENCES teams(id), revision INTEGER NOT NULL,
+  session_id TEXT, kind TEXT NOT NULL, created_at INTEGER NOT NULL,
+  PRIMARY KEY(team_id,revision), FOREIGN KEY(team_id,session_id) REFERENCES sessions(team_id,id)
+) STRICT;
+CREATE TABLE cursors (
+  id TEXT PRIMARY KEY, team_id TEXT NOT NULL REFERENCES teams(id), principal_id TEXT NOT NULL,
+  kind TEXT NOT NULL CHECK(kind IN ('list','search','history','session_events','catalog_events')),
+  query_json TEXT NOT NULL CHECK(json_valid(query_json)), auth_epoch INTEGER NOT NULL,
+  revision INTEGER NOT NULL, position INTEGER NOT NULL DEFAULT 0,
+  snapshot_json TEXT CHECK(snapshot_json IS NULL OR json_valid(snapshot_json)),
+  expires_at INTEGER NOT NULL, FOREIGN KEY(team_id,principal_id) REFERENCES memberships(team_id,principal_id)
+) STRICT;
+CREATE TABLE correlations (
+  team_id TEXT NOT NULL, id TEXT NOT NULL, left_session_id TEXT NOT NULL, right_session_id TEXT NOT NULL,
+  canonical_id TEXT NOT NULL, policy_json TEXT NOT NULL CHECK(json_valid(policy_json)),
+  evidence_json TEXT NOT NULL CHECK(json_valid(evidence_json)), revision INTEGER NOT NULL,
+  PRIMARY KEY(team_id,id), FOREIGN KEY(team_id,left_session_id) REFERENCES sessions(team_id,id),
+  FOREIGN KEY(team_id,right_session_id) REFERENCES sessions(team_id,id),
+  FOREIGN KEY(team_id,canonical_id) REFERENCES sessions(team_id,id)
+) STRICT;
+CREATE TABLE bindings (
+  team_id TEXT NOT NULL, id TEXT NOT NULL, machine_id TEXT NOT NULL, session_id TEXT NOT NULL,
+  incarnation_id TEXT NOT NULL, descriptor_json TEXT NOT NULL CHECK(json_valid(descriptor_json)),
+  observed_at INTEGER NOT NULL, PRIMARY KEY(team_id,id),
+  FOREIGN KEY(team_id,machine_id) REFERENCES machines(team_id,id),
+  FOREIGN KEY(team_id,session_id) REFERENCES sessions(team_id,id)
+) STRICT;
+CREATE TABLE live_grants (
+  team_id TEXT NOT NULL, id TEXT NOT NULL, machine_id TEXT NOT NULL, session_id TEXT NOT NULL,
+  binding_id TEXT NOT NULL, subject_id TEXT NOT NULL, actions_json TEXT NOT NULL CHECK(json_valid(actions_json)),
+  expires_at INTEGER NOT NULL, revision INTEGER NOT NULL DEFAULT 1,
+  PRIMARY KEY(team_id,id), FOREIGN KEY(team_id,machine_id) REFERENCES machines(team_id,id),
+  FOREIGN KEY(team_id,session_id) REFERENCES sessions(team_id,id),
+  FOREIGN KEY(team_id,binding_id) REFERENCES bindings(team_id,id),
+  FOREIGN KEY(team_id,subject_id) REFERENCES memberships(team_id,principal_id)
+) STRICT;
+CREATE TABLE attachments (
+  team_id TEXT NOT NULL, id TEXT NOT NULL, requester_id TEXT NOT NULL,
+  issuer_credential_id TEXT NOT NULL REFERENCES credentials(id),
+  machine_id TEXT NOT NULL, binding_id TEXT NOT NULL, session_id TEXT NOT NULL,
+  incarnation_id TEXT NOT NULL, mode TEXT NOT NULL CHECK(mode IN ('observe','control')),
+  access_revision INTEGER NOT NULL, grant_id TEXT NOT NULL,
+  effective_actions_json TEXT NOT NULL CHECK(json_valid(effective_actions_json)),
+  stream_token_hash TEXT NOT NULL UNIQUE, stream_token_expires_at INTEGER NOT NULL,
+  stream_token_consumed_at INTEGER, grant_expires_at INTEGER NOT NULL,
+  last_sequence INTEGER NOT NULL DEFAULT -1 CHECK(last_sequence >= -1),
+  state TEXT NOT NULL CHECK(state IN ('pending','active','detached','revoked','closed')),
+  created_at INTEGER NOT NULL, closed_at INTEGER,
+  PRIMARY KEY(team_id,id),
+  FOREIGN KEY(team_id,requester_id) REFERENCES memberships(team_id,principal_id),
+  FOREIGN KEY(team_id,machine_id) REFERENCES machines(team_id,id),
+  FOREIGN KEY(team_id,binding_id) REFERENCES bindings(team_id,id),
+  FOREIGN KEY(team_id,session_id) REFERENCES sessions(team_id,id),
+  FOREIGN KEY(team_id,grant_id) REFERENCES live_grants(team_id,id)
+) STRICT;
+CREATE INDEX attachments_binding_state ON attachments(team_id,binding_id,state);
+CREATE TABLE continuations (
+  team_id TEXT NOT NULL, id TEXT NOT NULL, requester_id TEXT NOT NULL, source_session_id TEXT NOT NULL,
+  state TEXT NOT NULL, value_json TEXT NOT NULL CHECK(json_valid(value_json)), expires_at INTEGER NOT NULL,
+  PRIMARY KEY(team_id,id), FOREIGN KEY(team_id,requester_id) REFERENCES memberships(team_id,principal_id),
+  FOREIGN KEY(team_id,source_session_id) REFERENCES sessions(team_id,id)
+) STRICT;
+CREATE TABLE operations (
+  team_id TEXT NOT NULL, id TEXT NOT NULL, requester_id TEXT NOT NULL, session_id TEXT NOT NULL,
+  state TEXT NOT NULL CHECK(state IN ('pending','running','succeeded','failed','unknown')),
+  value_json TEXT NOT NULL CHECK(json_valid(value_json)), created_at INTEGER NOT NULL,
+  PRIMARY KEY(team_id,id), FOREIGN KEY(team_id,requester_id) REFERENCES memberships(team_id,principal_id),
+  FOREIGN KEY(team_id,session_id) REFERENCES sessions(team_id,id)
+) STRICT;
+CREATE TABLE native_effects (
+  team_id TEXT NOT NULL, id TEXT NOT NULL, operation_id TEXT NOT NULL, principal_id TEXT NOT NULL,
+  issuer_credential_id TEXT NOT NULL REFERENCES credentials(id),
+  machine_id TEXT NOT NULL, binding_id TEXT, incarnation_id TEXT NOT NULL, session_id TEXT NOT NULL,
+  access_revision INTEGER NOT NULL, grant_id TEXT, expires_at INTEGER NOT NULL,
+  kind TEXT NOT NULL CHECK(kind IN ('attach','input','approve','interrupt','terminate','continue')),
+  payload_json TEXT NOT NULL CHECK(json_valid(payload_json)),
+  state TEXT NOT NULL CHECK(state IN ('pending','running','succeeded','failed','unknown')),
+  result_json TEXT CHECK(result_json IS NULL OR json_valid(result_json)), claimed_at INTEGER,
+  PRIMARY KEY(team_id,id), UNIQUE(team_id,operation_id),
+  CHECK(kind='continue' OR (grant_id IS NOT NULL AND binding_id IS NOT NULL)),
+  FOREIGN KEY(team_id,principal_id) REFERENCES memberships(team_id,principal_id),
+  FOREIGN KEY(team_id,operation_id) REFERENCES operations(team_id,id),
+  FOREIGN KEY(team_id,machine_id) REFERENCES machines(team_id,id),
+  FOREIGN KEY(team_id,binding_id) REFERENCES bindings(team_id,id),
+  FOREIGN KEY(team_id,grant_id) REFERENCES live_grants(team_id,id),
+  FOREIGN KEY(team_id,session_id) REFERENCES sessions(team_id,id)
+) STRICT;
+CREATE INDEX native_effects_machine_state ON native_effects(team_id,machine_id,state,id);
+CREATE TABLE idempotency (
+  team_id TEXT NOT NULL, principal_id TEXT NOT NULL, route TEXT NOT NULL, key TEXT NOT NULL,
+  request_digest TEXT NOT NULL, response_status INTEGER NOT NULL, response_json TEXT NOT NULL,
+  expires_at INTEGER NOT NULL, PRIMARY KEY(team_id,principal_id,route,key),
+  FOREIGN KEY(team_id,principal_id) REFERENCES memberships(team_id,principal_id)
+) STRICT;
+CREATE TABLE global_idempotency (
+  principal_id TEXT NOT NULL REFERENCES principals(id), route TEXT NOT NULL, key TEXT NOT NULL,
+  request_digest TEXT NOT NULL, response_status INTEGER NOT NULL, response_json TEXT NOT NULL,
+  expires_at INTEGER NOT NULL, PRIMARY KEY(principal_id,route,key)
+) STRICT;
+CREATE TABLE global_cursors (
+  id TEXT PRIMARY KEY, principal_id TEXT NOT NULL REFERENCES principals(id),
+  credential_team_id TEXT REFERENCES teams(id), kind TEXT NOT NULL,
+  query_json TEXT NOT NULL CHECK(json_valid(query_json)),
+  snapshot_json TEXT NOT NULL CHECK(json_valid(snapshot_json)), expires_at INTEGER NOT NULL
+) STRICT;
+CREATE INDEX global_cursors_expiry ON global_cursors(expires_at);
+CREATE TABLE evidence (
+  team_id TEXT NOT NULL, source_id TEXT NOT NULL, id TEXT NOT NULL, native_event_key TEXT,
+  signal TEXT NOT NULL CHECK(signal IN ('logs','traces','metrics')), raw_json TEXT NOT NULL CHECK(json_valid(raw_json)),
+  received_at INTEGER NOT NULL, decode_state TEXT NOT NULL,
+  PRIMARY KEY(team_id,id), UNIQUE(team_id,source_id,native_event_key),
+  FOREIGN KEY(team_id,source_id) REFERENCES sources(team_id,id)
+) STRICT;
+CREATE TABLE audit (
+  team_id TEXT NOT NULL REFERENCES teams(id), id TEXT NOT NULL, actor_id TEXT NOT NULL,
+  operation TEXT NOT NULL, target_id TEXT, outcome TEXT NOT NULL, revision INTEGER, created_at INTEGER NOT NULL,
+  PRIMARY KEY(team_id,id)
+) STRICT;
+CREATE INDEX messages_search_scope ON messages(team_id,session_id,revision);
+CREATE INDEX versions_sort ON session_versions(team_id,sort_at DESC,session_id);
+CREATE INDEX journal_replay ON journal(team_id,session_id,revision);
+CREATE INDEX cursors_expiry ON cursors(expires_at);
+CREATE INDEX credentials_scope ON credentials(team_id,source_id,machine_id);
+PRAGMA user_version = 1;
+`;

package/server/migrations/002.mjs

@@ -0,0 +1,13 @@
+// Schema migration 002 (SQLite DDL), applied in order by store-core migrate().
+export default `-- Schema 2: machine grants (design §11). A subject (member, service account or
+-- group) holds capabilities on one machine's doors until an expiry. The
+-- machine re-derives admission from its own synced copy of these rows.
+CREATE TABLE machine_grants (
+  team_id TEXT NOT NULL, id TEXT NOT NULL, machine_id TEXT NOT NULL, subject_id TEXT NOT NULL,
+  caps_json TEXT NOT NULL CHECK(json_valid(caps_json)), targets_json TEXT NOT NULL CHECK(json_valid(targets_json)),
+  issuer_id TEXT NOT NULL, created_at INTEGER NOT NULL, expires_at INTEGER NOT NULL, revision INTEGER NOT NULL DEFAULT 1,
+  PRIMARY KEY(team_id,id), FOREIGN KEY(team_id,machine_id) REFERENCES machines(team_id,id)
+) STRICT;
+CREATE INDEX machine_grants_subject ON machine_grants(team_id,machine_id,subject_id,expires_at);
+ALTER TABLE machines ADD COLUMN host_key_id TEXT;
+`;

package/server/migrations/003.mjs

@@ -0,0 +1,11 @@
+// Schema migration 003 (SQLite DDL), applied in order by store-core migrate().
+export default `-- Schema 3: a principal's linked identities (protocol P02, federation). A person
+-- signed in with an identity service (Volter, id.volter.ai) is the principal
+-- whose row names that issuer and subject; the principal id never changes, so
+-- federation keeps every id minted before it.
+CREATE TABLE principal_identities (
+  issuer TEXT NOT NULL, subject TEXT NOT NULL,
+  principal_id TEXT NOT NULL REFERENCES principals(id), linked_at INTEGER NOT NULL,
+  PRIMARY KEY(issuer,subject), UNIQUE(principal_id,issuer)
+) STRICT;
+`;

package/server/migrations/004.mjs

@@ -0,0 +1,35 @@
+// Schema migration 004 (SQLite DDL), applied in order by store-core migrate().
+export default `-- Schema 4: grants name the kind they reach (RFC 0008). \`*\` keeps only operate and
+-- view. A grant holding other capabilities on \`*\` is split: view (if it had it) stays on
+-- \`*\` in the original row, and the other capabilities move to a new row naming the
+-- harness kinds they covered (pane:*, runtime:*, root:/, port:*), so they never reach a
+-- kind added later. A \`browser:<pane>\` target only ever carried ports: it becomes
+-- \`pane:<pane>\` when ports is its only capability and is dropped otherwise. Rows that
+-- change get a new revision; the daemon resyncs when a claim's revision differs.
+INSERT INTO machine_grants(team_id,id,machine_id,subject_id,caps_json,targets_json,issuer_id,created_at,expires_at)
+SELECT team_id, id || '-kinds', machine_id, subject_id,
+  (SELECT json_group_array(value) FROM json_each(g.caps_json) WHERE value NOT IN ('operate','view')),
+  '["pane:*","runtime:*","root:/","port:*"]', issuer_id, created_at, expires_at
+FROM machine_grants g
+WHERE EXISTS (SELECT 1 FROM json_each(g.targets_json) WHERE value = '*')
+  AND NOT EXISTS (SELECT 1 FROM json_each(g.caps_json) WHERE value = 'operate')
+  AND EXISTS (SELECT 1 FROM json_each(g.caps_json) WHERE value NOT IN ('operate','view'));
+UPDATE machine_grants SET
+  caps_json = CASE WHEN EXISTS (SELECT 1 FROM json_each(machine_grants.caps_json) WHERE value = 'view') THEN '["view"]' ELSE caps_json END,
+  targets_json = CASE WHEN EXISTS (SELECT 1 FROM json_each(machine_grants.caps_json) WHERE value = 'view')
+    THEN (SELECT json_group_array(value) FROM json_each(machine_grants.targets_json))
+    ELSE (SELECT json_group_array(value) FROM json_each(machine_grants.targets_json) WHERE value <> '*') END,
+  revision = revision + 1
+WHERE id NOT LIKE '%-kinds'
+  AND EXISTS (SELECT 1 FROM json_each(machine_grants.targets_json) WHERE value = '*')
+  AND NOT EXISTS (SELECT 1 FROM json_each(machine_grants.caps_json) WHERE value = 'operate')
+  AND EXISTS (SELECT 1 FROM json_each(machine_grants.caps_json) WHERE value NOT IN ('operate','view'));
+DELETE FROM machine_grants WHERE targets_json = '[]';
+UPDATE machine_grants SET
+  targets_json = (SELECT json_group_array(CASE WHEN value LIKE 'browser:%' THEN 'pane:' || substr(value, 9) ELSE value END)
+    FROM json_each(machine_grants.targets_json)
+    WHERE value NOT LIKE 'browser:%' OR machine_grants.caps_json = '["ports"]'),
+  revision = revision + 1
+WHERE EXISTS (SELECT 1 FROM json_each(machine_grants.targets_json) WHERE value LIKE 'browser:%');
+DELETE FROM machine_grants WHERE targets_json = '[]';
+`;

package/server/migrations/index.mjs

@@ -0,0 +1,6 @@
+// The schema, in order: both hosts (Node and the Durable Object) apply the same DDL.
+import m001 from './001.mjs';
+import m002 from './002.mjs';
+import m003 from './003.mjs';
+import m004 from './004.mjs';
+export const MIGRATIONS = [m001, m002, m003, m004];